# Reverse Engineering Automation

PaiMei is a reverse engineering framework written to cut the development time of random RE ideas from weeks to hours: PyDbg, pGRAPH, PIDA, a pluggable console and a pile of scripts. It debuted at RECON 2006. The project is long retired and I recommend looking elsewhere for modern RE automation, but the code lives on at github.com/OpenRCE/paimei and the original documentation follows, as written in 2006.

Overview

Introduction

• PyDbg: A pure Python win32 debugging abstraction class.
• pGRAPH: A graph abstraction layer with seperate classes for nodes, edges and clusters.
• PIDA: Built on top of pGRAPH, PIDA aims to provide an abstract and persistent interface over binaries (DLLs and EXEs) with separate classes for representing functions, basic blocks and instructions. The end result is the creation of a portable file that when loaded allows you to arbitrarily navigate throughout the entire original binary.

• Utilities: A set of utilities for accomplishing various repetitive tasks.
• Console: A pluggable WxPython GUI for quickly and efficiently rolling out your own sexy RE utilities.
• Scripts: Individual scripts for accomplishing various tasks. One very important example of which is the pida_dump.py IDA Python script which is run from IDA to generate .PIDA modules.

PyDbg

    from pydbg import *
    from pydbg.defines import *
    
    def handler_breakpoint (pydbg):
       # ignore the first windows driven breakpoint.
       if pydbg.first_breakpoint:
           return DBG_CONTINUE
    
       log("ws2_32.recv() called from thread %d @%08x" % pydbg.dbg.dwThreadId, pydbg.exception_address)
    
       return DBG_CONTINUE
    
    dbg = pydbg()
    
    # register a breakpoint handler function.
    dbg.set_callback(EXCEPTION_BREAKPOINT, handler_breakpoint)
    dbg.attach(XXXXX)
    
    recv = dbg.func_resolve("ws2_32", "recv")
    dbg.bp_set(recv)
    
    pydbg.debug_event_loop()

PIDA

    import pida
    
    module = pida.load("some_file.pida")
    
    # render a function graph in GML format for the entire module.
    fh = open("graphs/functions.gml", "w+")
    fh.write(module.render_graph_gml())
    fh.close()
    
    # render a function graph in uDraw format for the entire module.
    fh = open("graphs/functions.udg", "w+")
    fh.write(module.render_graph_udraw())
    fh.close()
    
    # step through each function in the module:
    for function in module.nodes.values():
        # if we found the first function we are interested in
        if function.ea_start == 0x00407950:
            # step through each basic block in the function.
            for bb in function.nodes.values():
                print "\t%08x - %08x" % (bb.ea_start, bb.ea_end)
                # print each instruction in each basic block.
                for ins in bb.instructions.values():
                    print "\t\t%s" % ins.disasm
    
            # render a GML graph of this function.
            fh = open("graphs/function.gml", "w+")
            fh.write(function.render_graph_gml())
            fh.close()
    
            # render a GraphViz PNG of this function too.
            graph = function.render_graph_graphviz()
            graph.write_png("graphs/function.png", prog="dot")
    
        # if we found the second function we are interested in.
        if function.name == "some_routine":
            # render a GML format proximity graph.
            fh = open("graphs/proximity.udg", "w+")
            # look 3 levels up and 2 levels down
            prox_graph = module.graph_proximity(function.id, 3, 2)
            fh.write(prox_graph.render_graph_udraw())
            fh.close()

    # for each function in the module
    for function in module.functions.values():
        # create a downgraph from the current routine and locate the calls to [Open|Create]File[A|W]
        downgraph = module.graph down(function.ea start, -1)
        matches = [node for node in downgraph.nodes.values() if re.match(".*(create|open)file.*", node.name, re.I)]
        upgraph = pgraph.graph()
    
        # for each matching node create a temporary upgraph and add it to the parent upgraph.
        for node in matches:
            tmp_graph = module.graph up(node.ea start, -1)
            upgraph.graph cat(tmp_graph)
    
        # write the intersection of the down graph from the current function and the upgraph from
        # the discovered interested nodes to disk in gml format.
        downgraph.graph intersect(upgraph)
    
        if len(downgraph.nodes):
            fh = open("%s.gml" % function.name, "w+")
            fh.write(downgraph.render graph gml())
            fh.close()

Entity Relationship Diagram

Future Development

Installation

Quick Start

1. Install Python 2.4, Windows Python-2.4.3.msi
2. Launch __install_requirements.py and follow the interactive prompts to download / install requirements.
3. Launch __setup_mysql.py (requires command line arguments) to setup the MySQL database for pstalker.
4. Launch console\PAIMEIconsole.py to pull up the GUI.
5. Install IDA Python.
6. Launch IDA, load a target executable and run the pida_dump.py IDA Python script to generate a PIDA file.
7. Load the PIDA file in the GUI and you're up and running.

Detailed Installation Guide

Scripts and Tools

Debuggee Procedure Call (DPC)

    var = dpc(0xdeadbeef, "pedram")     # INCORRECT
    
    dpc(0xdeadbeef, "pedram")           # CORRECT
    var = dbg.context.Eax

    dpc(function, 10, "string", eax=0xdeadbeef, ecx="string")

    glob.string = "A" * 500
    glob.list   = []
    glob.mbox   = dbg.func_resolve("user32", "MessageBoxA")

• Allocate memory in the process.
• Reverse the argument list.
• For each numeric argument generate and write a PUSH instruction to the allocated block.
• For each string argument, allocate memory for the string then generate and write a PUSH instruction to the allocated block.
• For each specified register value, set it appropriately. If it is a string, allocate memory for the string and place the string address in the register.
• Generate and write a CALL instruction to the allocated block.
• Write an INT 3 (breakpoint) to the allocated block to resume debugger control and re-prompt the user for further inputs.

OllyDbg Connector / Receiver

• , < Step into (F7) and transmit current location to OllyDbg receiver.
• . > Step over (F8) and transmit current location to OllyDbg receiver.
• / ? Transmit current location to OllyDbg receiver.

    "C:\Program Files\uDraw(Graph)\bin\uDrawGraph.exe" -server

PIDA Dump / Load

Proc Peek / Proc Peek Recon

• <-r | --recon RECON FILE>: name of proc_peek_recon output file, this is the only required argument
• [-p | --pid PID]: pid to attach to (must specify this or watch)
• [-w | --watch PROC]: target name to watch for and attach to
• [-i | --ignore PID]: ignore a specific PID when watching for a target
• [-n | --noint]: disable interactive prompts
• [-q | --quiet]: disable run-time context dumps
• [-l | --log LOG FILE]: report to file instead of screen
• [-h | --host REMOTE HOST]: connect to a pydbg server
• [-b | --boron KEYWORD]: alert us when a keyword is found within the context
• [-t | --track_recv]: enable recv() and recvfrom() hit logging

Console (GUI) and Modules

Console Menus

Connectons\MySQL Connect

Connectons\PyDbg Locale

Connectons\uDraw(Graph) Connect

    "C:\Program Files\uDraw(Graph)\bin\uDrawGraph.exe" -server

Advanced\Clear Log

Advanced\Toggle Python Shell

Help\About

Console Command Line Interface

PAIMEdiff

PAIMEIdocs

PAIMEIexplore

PAIMEIfilefuzz

PAIMEIpstalker

Overview

1. Create a new target and/or tag. Targets can contain multiple tags and each individual tag contains it's own saved code coverage data.
2. Select a tag for staking.
3. Load PIDA modules for every .DLL and the .EXE you wish to stalk.
4. Launch your target.
5. Refresh the process list under the data capture panel and select your target process for attaching or browse to the target process for loading.
6. Configure the code coverage options and attach to the selected target.
7. Interact with your target while code coverage is being recorded.
8. When you are ready, detach from the target and wait for pstalker to export captured items to the database.
9. Load the recorded hits to begin exploring your recorded data.

Data Sources

• Load Hits, clear the data exploration pane and load the hits associated with the selected tag.
• Append Hits, append the hits associated with the selected tag after any existing data currently in the exploration pane.
• Export to IDA, export the hits under the selected tag as an IDC script suitable for import in IDA to highlight the hit functions / blocks.
• Sync with uDraw, synchronize the data exploration pane on the console-wide uDraw connection. Dual monitors are very helpful for this feature.
• Use for Stalking, store all recorded hits during data capture phase to the selected tag. You must select a tag for stalking prior to attaching to a process.
• Filter Tag, do not record hits for any of the nodes / basic blocks under the selected tag in future stalks. You can mark more then one tag for filtering.
• Clear Tag, keep the tag but remove all the hits stored under the tag. You can not stalk into a tag with any pre-existing data, so if you want to overwrite the contents of a tag be sure to clear it first.
• Expand Tag, for each hit function in the tag, generate and add an entry for every contained basic block, even if that basic block was not explicitly hit.
• Target/Tag Properties, modify the tag name, view/edit tag notes or modify the target name.
• Delete Tag, remove the tag and all the hits stored under the tag.

Data Exploration

Data Capture

Limitations

Developer Docs

Working with the Libraries

Overview

• pGRAPH
• PIDA
• PyDbg
• Utilities

pGRAPH

PIDA

PyDbg

Utilities

Creating GUI Modules

Overview

Structure

    images\icons\PAIMEIexplorer.png
    modules\PAIMEIexplorer.py

    modules\_PAIMEIexplorer\*

WxGlade

Functions and Variables

    documented_properties = {
        "pida_modules" : "Dictionary of loaded PIDA modules.",
    }

    self.list_book  = kwds["parent"]             # handle to list book.
    self.main_frame = self.list_book.top         # handle to top most frame. 
    

Interacting with the Status Bar

    ####################################################################################################################
    def _get_status (self):
        '''
        Return the text to display in the status bar on page change.
        '''
     
        return self.status_msg
     
    ####################################################################################################################
    def _set_status (self, status_msg):
        '''
        Set the text to display in the status bar.
        '''
     
        self.status_msg = status_msg
        self.main_frame.status_bar.SetStatusText(self.status_msg, 1)
    

Creating a Log Window

    self.Bind(wx.EVT_TEXT_MAXLEN, self.OnMaxLogLengthReached, self.log)
     
    ####################################################################################################################
    def OnMaxLogLengthReached (self, event):
        '''
        Clear the log window when the max length is reach.
        
        @todo: Make this smarter by maybe only clearing half the lines.
        '''
        
        self.log.SetValue("")

    self.log_splitter.SetMinimumPaneSize(25)

    ####################################################################################################################
    def err (self, message):
        '''
        Write an error message to log window.
        '''
     
        self.log.AppendText("[!] %s\n" % message)
     
     
    ####################################################################################################################
    def msg (self, message):
        '''
        Write a log message to log window.
        '''
     
        self.log.AppendText("[*] %s\n" % message)

Take Pride in your Work

    self.msg("PaiMei Explorer")
    self.msg("Module by Pedram Amini\n")

Some Final Notes

    for key in module.functions.keys():
        module.functions[key].ext["PAIMEIexplore"] = {}
        module.functions[key].ext["PAIMEIexplore"]["hit_count"] = 0