Please take a moment to read http://bit.ly/demandglobalchange, to help share the message and support the initiative to tell our leaders to focus on addressing the global world problems, instead of complaining about the effects of their lack of leadership. Be a leader yourself, and share this with as many people as possible. #demandglobalchange // https://www.facebook.com/demandglobalchange



Please consider donating: https://www.corelan.be/index.php/donate/


42,673 viewsThis page as PDF (Login first !)

Starting to write Immunity Debugger PyCommands : my cheatsheet

When I started Win32 exploit development many years ago, my preferred debugger at the time was WinDbg (and some Olly). While Windbg is a great and fast debugger, I quickly figured out that some additional/external tools were required to improve my exploit development experience.

Despite the fact that the command line oriented approach in windbg has many advantages, it appeared not the best tool to search for good jump addresses, or to list non-safeseh compiled / non-aslr aware modules, etc…. Ok, looking for a simple “jmp esp” is trivial, but what if you are looking for all pop pop ret combinations in non-safeseh compiled modules… Not an easy task.

It is perfectly possible to build plugins for Windbg, but the ones that I have found (MSEC, byakugan (Metasploit)) don’t always work the way I want them to work, and would still not solve some issues I was having while writing exploits.

OllyDbg and Immunity Debugger are quite different than windbg. Not only the GUI is very much different, the number of plugins for these debuggers is substantially higher. After evaluating both of them (they pretty much have the same look and feel), and evaluating the way plugins can be added, I made the decision to focus on Immunity Debugger.

That does not mean OllyDbg is a bad debugger or is limited in what you can do in terms of writing plugins… I just found it harder to “quickly tweak a plugin” while building an exploit. OllyDbg plugins are compiled into dll’s, so changing a plugin would require me to recompile and test. Immunity Debugger uses python scripts. I can go into the script, make a little change, and see the results right away. Simple.

Both OllyDbg and Immunity Debugger have a good amount of plugins (either contributed by the community or made available when you installed the product). While there is nothing wrong with these plugins (or PyCommands in case of Immunity Dbg), I really wanted to have a single plugin that would help me building all (stack based) exploits, from A to Z. This idea got translated into my pvefindaddr PyCommand.

My obvious choice was Immunity & Python. I’m not a great python developer (at all), but I have been able to build my own PyCommand in a relatively short amount of time. This proves that it’s really easy to build custom PyCommands for Immunity, even if you are not an expert developer. If I can do it, then you can for sure.

The only issue I faced (apart from learning python syntax and getting used to python’s hmmmm “slightly annoying” indentation requirement) was finding out how the Immunity-specific API’s/methods/attributes work. To be honest, the API help included with Immunity Debugger was not a great help. It basically only lists the available methods/attributes/… and that’s it. No explanation on what these methods & attributes behave, on what they’re supposed to do, or how to use them for that matter. Ok, once you start understanding how things work, they are still a good reference, but when you are learning from scratch, a little persistence may be required.

Luckily, since Immunity comes with a lot of PyCommands, those can be used as a reference.

Anyways, it’s still a good idea to use the ImmDbg Python API help file too. You can get access to the API help in Immunity by navigating to “Help”, select “Select API help file”, and selecting the IMMLIB.HLP file from the Documentation folder.

image

From that point forward, you can access this help file via “Help” – “Open API help file”

image

Immunity also has an online version of the API : http://debugger.immunityinc.com/update/Documentation/ref/ (online version contains a little bit more information)

My main goal today is putting together a reference/cheatsheet for anyone interested in writing pycommands, so you can start building your own plugins faster than I did :-) ). This is not going to be “the complete reference”, but it should help you start to build your own plugins.

First of all, the python syntax that you will need to write (or learn and write) is based on python 2.x (If you are not familiar with python : v2.x and v3.x are quite different in certain areas, so if you want to get yourself a reference/book on writing python, make sure to pick one that is based on the 2.x branch)

Building a PyCommand from scratch

Start by creating a file in the Immunity Debugger PyCommands folder : .py

This filename is important, because you will need to launch the PyCommand based on the filename.

Launching a PyCommand

Launching a PyCommand is really easy : just type in the filename (without the .py extension, but prepended with an exclamation mark), in the command box at the bottom of Immunity Debugger

image

So if you named your plugin “plugin1.py”, then you can launch the script by executing

!plugin1

Basic structure

The basic structure of a plugin looks like this :

– load the Immunity Libraries (and perhaps other libraries, depending on what you want to do)

– write a main() function that will read the command line arguments (if any) and call functions based on what you want the plugins to do

– write the functions that will perform the required actions

#!/usr/bin/env python
"""
(c) Peter Van Eeckhoutte 2009
U{Peter Van Eeckhoutte - corelan.//www.corelan.be>}

peter.ve@corelan.be
corelanc0d3r

"""
__VERSION__ = '1.0'
import immlib
import getopt
import immutils
from immutils import *

""""""""""""
 Functions
""""""""""""



""""""""""""""""""
 Main application
""""""""""""""""""
def main(args):

Next, you will need to specify you want to use the Immunity Debugger libraries and use them in your script. The best way to do is by declaring a variable that hooks into the Immunity debugger class:

imm = immlib.Debugger()

I usually make this one global, so I keep it outside of the main() function. (You can put it directly below the “import” statements for example)

The list of available classes are :

image

Handling arguments

The arguments/parameters specified when launching the PyCommand are captured in the “args” array.

You can get the number of arguments using

len(args)

Accessing the arguments themselves is as easy as iterating through the args[] array and getting the contents of an element in the array:

def main(args):
    if not args:
        usage()
    else:
        print "Number of arguments : " + str(len(args))
        cnt=0
        while (cnt < len(args)):
            print " Argument " + str(cnt+1)+" : " + args[cnt]
            cnt=cnt+1

Writing to log, tables, files

You may have noticed that the script above does not seem to output anything. While the syntax is perfectly correct, there is no visible default output window, so you will have to tell the plugin where to write the output to.

There are a couple of options : you can write to the Immunity Log window (which is the most commonly used technique), a new/separate table (which is nothing more than a new window that can list the information in a table), or to a file (which may be a good idea if the amount of output you are generating would overflow the Log window buffer.

Writing output to the Log Window

The Log Window is a part of the debugger. So we will need to use the debugger instance that we have declared earlier (imm) to write to the Log.

The method to do so is simple : imm.Log()

image

There are a couple of things you can do, so let’s have a look at this example :

def main(args):
	print "Number of arguments : " + str(len(args))
	imm.Log("Number of arguments : %d " % len(args))
	cnt=0
	while (cnt < len(args)):
		imm.Log(" Argument %d : %s" % (cnt+1,args[cnt]))
		if (args[cnt] == "world"):
			imm.Log("  You said %s !" % (args[cnt]),focus=1, highlight=1)
		cnt=cnt+1

image

You can specify a custom memory address in the left column of the Log Window. (If nothing is specified, this address will be 0BADF00D.) All you need to do is specify the memory address (integer !) as second argument for the Log() method :

def main(args):
	print "Number of arguments : " + str(len(args))
	imm.Log("Number of arguments : %d " % len(args))
	cnt=0
	while (cnt < len(args)):
		imm.Log(" Argument %d : %s" % (cnt+1,args[cnt]),12345678)
		if (args[cnt] == "world"):
			imm.Log("  You said %s !" % (args[cnt]),focus=1, highlight=1)
		cnt=cnt+1

image

A good way to start your plugin, handling “no arguments” by displaying a “Usage” text, could be something like this :

__VERSION__ = '1.0'
import immlib
import getopt
import immutils
from immutils import *
imm = immlib.Debugger()

"""
Functions
"""

def usage():
    imm.Log("  ** No arguments specified ** ")
    imm.Log("  Usage : ")
    imm.Log("       blah blah")

    
"""
Main application
"""
def main(args):
    if not args:
        usage()
    else:
        imm.Log("Number of arguments : %d " % len(args))
        cnt=0
        while (cnt < len(args)):
            imm.Log(" Argument %d : %s" % (cnt+1,args[cnt]))
            if (args[cnt] == "world"):
                imm.Log("  You said %s !" % (args[cnt]),focus=1, highlight=1)
            cnt=cnt+1

Updating log/table

You will notice, as you continue to build your plugin, that when you search through memory (or perform any other CPU intensive task), the log window may not get updated right away. Immunity may appear to be hanging for a while, and when everything completes, everything is shown in the log window (or table for that matter).

There is a way to influence this behaviour. After each imm.Log() call, you can force Immunity Debugger to update the log window. This is as easy as writing the following statement in your code :

imm.updateLog()

The only (big) disadvantage is that it will also slow down the CPU intensive task that you were performing. So it’s a trade off between seeing what happens in real time, and speed. It’s up to you to decide.

Writing output to a table

Writing data to the Log allows you to display both structured and unstructured data. First, you must define the table (Table title + colum titles), and then you can use the .add() method on the table object to add data to the table :

def main(args):
    if not args:
        usage()
    else:
        #create table
        table=imm.createTable('Argument table',['Number','Argument'])
        imm.Log("Number of arguments : %d " % len(args))
        cnt=0
        while (cnt < len(args)):
            table.add(0,["%d"%(cnt+1),"%s"%(args[cnt])])
            cnt=cnt+1

image

Writing output to a file

Writing output to the Log or a table works fine, as long as the amount of data doesn’t overflow the available amount of Log buffer space. If that is the case, you could consider writing output to file as well as to Log or a table.

This is not Immunity specific in any way – it’s just python code.

When writing files, by default, the files will be written into the Immunity Debugger program folder. The technique is simple :

filename="myfile.txt"
FILE=open(filename,"a")  #this will append to the file
FILE.write("Blah blah" + "\n")    
FILE.close()

What I usually do is this : First, I clear the contents of the file, then I append data to the file using a function (tofile())

Clearing the contents of a file can be done like this :

def resetfile(file1):
    FILE=open(file1,"w")
    FILE.write("")
    FILE.close()
    return ""    

At the beginning of a function, I reset the file, and in the function, I use the tofile() function to write data into the file

def tofile(info,filename):
    info=info.replace('\n',' - ')
    FILE=open(filename,"a")
    FILE.write(info+"\n")    
    FILE.close()    
    return ""

Working with addresses

When you have to display a memory address, or use a memory address in a function, then you must verify what the required format of the address should be : either a string (if you only want to display the address) or an integer (if the address is used in Immunity methods)

When Immunity returns an address or expects you to provide an address, it will be an integer. If you want to display this address on screen, write to a log file, etc… you’ll have to use a format string to convert it to readable format :

def usage():
   imm.Log("  ** No arguments specified ** ")
   imm.Log("  Usage : ")
   imm.Log("       blah blah")

def tohex(intAddress):
   return "%08X" % intAddress
    
"""
Main application
"""
def main(args):
   if not args:
      usage()
   else:
      myAddress=1234567  #integer address
      imm.Log(" Integer         : %d " % myAddress,address=myAddress)
      imm.Log(" Readable hex    : 0x%08X" % myAddress,address=myAddress)
      hexAddress = tohex(myAddress)
      imm.Log(" Readable string : 0x%s" % hexAddress,address=myAddress)
      imm.Log(" Back to integer : %d" % int(hexAddress,16),address=int(hexAddress,16))

image

Remember : anytime the Immunity API says a method uses “address”, you need to specify an integer value.

Ok, that’s all we need to know for now – we can start writing code that will actually do something usefull and display the output to log, table, file, …

Using opcodes, assemble and disassemble, and searching memory

One of the most common things you’ll probably want to do is search through memory, looking for specific type of information. Some examples could be

– finding jump addresses (jump, call, push+ret, pop pop ret, etc)

– comparing bytes in memory with bytes in a file (so step through memory locations, read bytes, and do something with it)

– etc

In certain cases, you’ll probably also want to convert opcodes to instructions, and vice versa.

Let’s take it step by step. Suppose you want to search for all jmp esp instructions available in memory. First of all, there has to be a process attached to Immunity before your search will produce results. No process = no results :-)

There are 2 ways to perform a search. You can provide the asm code, use Immunity to convert it to opcodes, and perform the search; or you can provide the opcode and perform the search.

Example 1 : search for “jmp esp”

def main(args):
   imm.Log("Started search for jmp esp...")
   imm.updateLog()
   searchFor="jmp esp"
   results=imm.Search( imm.Assemble (searchFor) )
   for result in results:
      imm.Log("Found %s at 0x%08x " % (searchFor, result), address = result)
      
      

That wasn’t too bad, was it ?

Example 2 : If you want to search for a serie of instructions (such as “push esp + ret”), then the instructions must be separated by \n :

def main(args):
   imm.Log("Started search for push esp / ret...")
   imm.updateLog()
   searchFor="push esp\nret"
   results=imm.Search( imm.Assemble (searchFor) )
   for result in results:
      imm.Log("Found %s at 0x%08x " % (searchFor.replace('\n',' - '), result), address = result)

Example 3 :

If you want to use opcode directly (instead of instructions), then

– the search looks a little bit different (no need to Assemble first)

– you can disassemble the instruction at the found address using the Disasm() + getDisasm() functions

def main(args):
   imm.Log("Started search for mov ebp,esp ")
   imm.updateLog()
   searchFor="\x8b\xec" #mov ebp,esp / ret
   results=imm.Search( searchFor )
   for result in results:
      opc = imm.Disasm( result )
      opstring=opc.getDisasm()   
      imm.Log("Found %s at 0x%08x " % (opstring, result), address = result)

Note : when you search through memory, it will search all process memory (loaded modules and outside loaded modules, but always limited to the memory that is used in the process). As stated earlier, searching through memory can make your CPU spike to 100%.

Writing your own assembler…

… is as easy as doing this :

__VERSION__ = '1.0'
import immlib
import getopt
import immutils
from immutils import *
imm = immlib.Debugger()
import re

    
"""
Main application
"""
def main(args):
   if (args[0]=="assemble"):
      if (len(args) < 2):
         imm.Log("  Usage : !plugin1 compare instructions")
         imm.Log("           separate multiple instructions with #")
      else:
         cnt=1
         cmdInput=""
         while (cnt < len(args)):
            cmdInput=cmdInput+args[cnt]+" "
            cnt=cnt+1
         cmdInput=cmdInput.replace("'","")
         cmdInput=cmdInput.replace('"','')
         splitter=re.compile('#')
         instructions=splitter.split(cmdInput)
         for instruct in instructions:
            try:
               assembled=imm.Assemble( instruct )
               strAssembled=""
               for assemOpc in assembled:
                  strAssembled =  strAssembled+hex(ord(assemOpc)).replace('0x', '\\x')
               imm.Log(" %s = %s" % (instruct,strAssembled))
            except:
               imm.Log("   Could not assemble %s " % instruct)
               continue

(I added “import re’” at the beginning of the script so I could use the splitter (re.compile()))

image

Stepping through memory

There may be a case where you would like to read memory from a given start location and get the bytes in memory. This can be done using the following technique :

if (args[0]=="readmem"):
   if (len(args) > 1):
      imm.Log("Reading 8 bytes of memory at %s " % args[1])
      cnt=0
      memloc=int(args[1],16)
      while (cnt < 8):
         memchar = imm.readMemory(memloc+cnt,1)
         memchar2 = hex(ord(memchar)).replace('0x','')
         imm.Log("Byte %d : %s" % (cnt+1,memchar2))
         cnt=cnt+1

The readMemory() method requires 2 arguments : the location where you want to read, and the amount of bytes to read.

image

Registers

Getting access to the registers is pretty straightforward too :

regs = imm.getRegs()
for reg in regs:
   imm.Log("Register %s : 0x%08X " % (reg,regs[reg]))

SEH chain

def main(args):
   if (args[0]=="sehchain"):         
      thissehchain=imm.getSehChain()
      sehtable=imm.createTable('SEH Chain',['Address','Value'])
      for chainentry in thissehchain:
         sehtable.add(0,("0x%08x"%(chainentry[0]),("%08x"%(chainentry[1]))))

image

Address & Module properties

When your script is searching through memory, and it retrieves an address, there may be certain things you want to know about the address:

– does it belong to a module and if so, which one ?

– what is the baseaddress and size of the module ?

– is this module compiled with safeseh or not ?

– is this module alsr aware or not ?

– what is the access level at a given memory location ?

Very good questions, and all of them can be solved in your script

We’ll pretend you have performed a search, and “result” is an element in the search results array.

See if a an address belongs to a module

module = imm.findModule(result)
if not module:
   module="none"
else:
   module=module[0].lower()

Module baseaddress and size

modbase=module.getBaseAddress()
modsize=module.getSize()
modtop=modbase+modsize   

Is this module compiled with safeseh ?

(this piece of code requires you to “import struct” at the beginning of the code)

module = imm.findModule(result)
#
mod=imm.getModule(module[0])
mzbase=mod.getBaseAddress()
peoffset=struct.unpack('flags=struct.unpack('unpack('if numberofentries>10:
   sectionaddress,sectionsize=struct.unpack('data=struct.unpack('data))
   if condition==False:
      imm.Log("Module %s is not safeseh protected" % module[0])
      continue

Is this module aslr aware or not ?

module = imm.findModule(result)
mod=imm.getModule(module[0])
mzbase=mod.getBaseAddress()
peoffset=struct.unpack('flags=struct.unpack('if (flags&0x0040)==0:
    imm.Log("Module %s is not aslr aware" % module[0])

Access level

page = imm.getMemoryPagebyAddress( result )
access = page.getAccess( human = True )
imm.Log("Access : %s" % access)

Combined into one script :

if (args[0]=="test"):
   imm.Log("Started search for mov ebp,esp ")
   imm.updateLog()
   searchFor="\x8b\xec" #mov ebp,esp / ret
   results=imm.Search( searchFor )
   for result in results:
      opc = imm.Disasm( result )
      opstring=opc.getDisasm()
      module = imm.findModule(result)
      if not module:
         module="none"
      else:
         page = imm.getMemoryPagebyAddress( result )
         access = page.getAccess( human = True )
         mod=imm.getModule(module[0])
         mzbase=mod.getBaseAddress()
         peoffset=struct.unpack('flags=struct.unpack('unpack('if numberofentries>10:
            sectionaddress,sectionsize=struct.unpack('data=struct.unpack('data))
            if condition==False:
              imm.Log("Module %s is not safeseh protected" % module[0],highlight=1)
              continue         
         if (flags&0x0040)==0:
            extrastring="not ASLR aware"
         else:
            extrastring="ASLR protected"
         imm.Log("Found %s at 0x%08x - [module %s] - access %s - ASLR : %s " % (opstring, result,module[0],access,extrastring), address = result)   

Debugged application : Name and path

If you want to (dynamically) filter out the name of the loaded executable (and get the path as well), you can use the following methods :

name=imm.getDebuggedName()
imm.Log("Name : %s" % name)
me=imm.getModule(name)
path=me.getPath()
imm.Log("Path : %s" % path)

Impact of upgrading to Immunity Debugger v1.74 and above

Immunity plans to fix some method/attribute inconsistencies (especially with uppercase/lowercase characters in the function/method names) in a newer version of Immunity (and the Immunity libraries). As a result of that, you may have to fix your PyCommand in order to make it work with newer versions of the debugger.

This is an overview of what you probably will need to fix :

Current v1.73 newer versions
.Log .log
.Assemble .assemble
.Disassemble .disassemble
.Search .search
.getMemoryPagebyAddress .getMemoryPageByAddress

Final words

This reference is far from complete and there is a lot more you can do with the Immunity API. I only wanted to give you a head start if you want to build your own PyCommands.

If you have built your own new PyCommand, share it with others – I’m sure other people can benefit from your work too.

Useful Links

http://www.tuts4you.com/download.php?list.72

http://www.defcon.org/images/defcon-15/dc15-presentations/dc-15-gomez.pdf

http://www.abysssec.com/blog/2010/01/immunity-debugger-pedetect-and-the-art-of-signature-generation/

http://beist.org/research/public/immunity1/imm_present_jff.pdf

2010 – 2015, Corelan Team (corelanc0d3r). All rights reserved.

Related Posts:

8 Responses to Starting to write Immunity Debugger PyCommands : my cheatsheet

  • fr0zen.sm0ke says:

    Thanks,
    I visit your blog everyday in a hope to find something new and download the stuff whenever you post a new article :)
    I dunno how good your articles are. I never read them. Download them in a hope that I am gonna read them in near future.
    I am learning Win32 assembly from Iczelion’s tutorial series. Exploit writing is my one of the dream. But not sure am I walking on the right path.
    Can you please guide me?
    You can consider me a good script kiddie in almost all domains. I’ve OK programming knowledge in ‘C’, python and bash. Has cleared Offsec 101 Pentest with BT cert.
    I wanna do “vulnerability research” and ‘exploitation’ in future.

    Thanks

    • Hey fr0zen.sm0oke

      I would suggest to start reading them and compile the list of skills that you would need to get better at it based on what you read. My tutorials are really written bottom up, so if you start reading at #1, then no real prerequisites are required (other than being able to read some basic lines of perl/C

      Good luck

      Peter

  • Redsees says:

    wow , what a great article !
    Congratulations Peter , it’s really useful for everyone ( and specifically VERY VERY USEFUL for me )!
    Good luck.
    Regards
    Jacky

  • PieterB says:

    Wonderful article!
    Installed Immunity Debugger in an XP VM immediately.
    You should check out Immunity’s CANVAS tool also (a whole different kind of tool…), I think it’s also mentioned in a book from syngress.

  • softproer says:

    very useful…
    thanks!

  • johnnycannuk says:

    Peter,

    Have you thought of doing one for PyHooks? I’m having some difficulty with them and as you say, the docs are less than complete.

  • fasmotol says:

    Hi. I share opinion of johnnycannuk – it’s some sort of cod’s wallop about hooks. So, the trick is that run procs are executed, but there is magic about it’s work… Actually strange things are – reinitializing variable in a own hook class; also u can write only 1 log() – others seem to be ignored etc. If u’ve been successful with hooks, please let us know. It’s obviously the problem is in ID files but the level of my python is too low for work like that.

Corelan Live training

Since 2011, Corelan GCV has been teaching live win32 exploit dev classes at various security cons and private companies & organizations.

You can read more about the training and schedules here

Demand Global Change

The world needs your help !

Please take a few moments to read the "Demand Global Change Call For Action" document at
http://bit.ly/demandglobalchange
Read the full document at
http://bit.ly/demandglobalchange_full and share the message with as many people as possible.

Like the Facebook page, and SHARE it with everyone you know.



Donate

Want to support the Corelan Team community ? Click here to go to our donations page.

Want to donate BTC to Corelan Team?



Your donation will help funding server hosting.

Protected by Copyscape Web Plagiarism Tool

Corelan Team Merchandise

You can support Corelan Team by donating or purchasing items from the official Corelan Team merchandising store.

Corelan on IRC

You can chat with us and our friends on #corelan (freenode IRC)

Categories