Console (GUI) and Modules

Table of Contents

  1. Overview
  2. Installation
  3. Scripts and Tools
  4. Console (GUI) and Modules
  5. Developer Docs

Console Menus

Connectons\MySQL Connect

Establish a console wide connection to your database server. A MySQL connection is required for example in the pstalker module.

Connectons\PyDbg Locale

This option controls the console wide PyDbg setting of whether to debug remotely or locally. In the public release of PaiMei, only local debugging is supported and therefore you should never need to change this option.

Connectons\uDraw(Graph) Connect

Establish a console wide socket connection to udraw(Graph). A connection to uDraw is required only if you plan on doing dynamic graphing. The pstalker "uDraw Sync" command for example requires uDraw connectivity. Note: uDraw must be started with the -server option in order to be in listening mode. Example: 
    "C:\Program Files\uDraw(Graph)\bin\uDrawGraph.exe" -server

Advanced\Clear Log

Clear the log window of the currently selected module.

Advanced\Toggle Python Shell

Show or hide the PaiMei command line interface.

Help\About

Display the about dialog box.

Console Command Line Interface

The CLI is toggled with the Advanced\Toggle Python Shell menu option. Using the CLI, you can accomplish various advanced tasks that are otherwise not accessible through the GUI. The top level variable for accessing the namespace within the console is paimei, a shortcut alias of simply p is also available. While every attribute of each module will be accessible to your through the CLI, the author of any given module has the ability to document specific variables that you will likely be interested in. The documentation for the global and per module namespace is available on the right hand side of the CLI interface. Select the module (or 'PaiMei' for global) from the drop down to display a list of exposed variables. Select a variable to reveal the description. The CLI is a fully functional Python interpreter, so feel free to execute any Python statement or import any module you desire.

PAIMEdiff

This module has not yet been publicly released.

PAIMEIdocs

This module defaults to loading the documentation you are currently reading. Use the drop down menu at the top to select another category of documentation.

PAIMEIexplore

The public release of this module is sort of the "hello world" of the PaiMei console. Load a PIDA module into the top list control, then double click on it to load it into the tree control. Explore the various functions and basic blocks within the PIDA module. A full disassembly is displayed in the center panel. Connect to uDraw and view the control-flow graph of individual functions through the right-click context menu.

PAIMEIfilefuzz

TODO: add docs

PAIMEIpstalker

The pstalker module is intended to replace the earlier developed Process Stalker code coverage tool. While the currently exposed feature set is not as robust at what was previously possible using the various command line utilities, one of the biggest improvements to Process Stalker is the storage of metadata to MySQL as opposed to multiple files that can quickly get disorganized and confusing.

Overview

The pstalker module is broken into three distinct columns. Data Sources, which is where you manage and create the targets you are stalking as well as load the appropriate PIDA modules. Data Exploration, where you can view the results of any individual code coverage run or "stalk". Data Capture, which is where you select the process and options to stalk. The general workflow associated with this tool is as follows, read on for specifics:
  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.
The following sections provide more specific documentation about each of the three overall columns.

Data Sources

After you first establish console-wide MySQL connectivity, hit the "Retrieve Target List" button to propogate the data source explorer tree. Obviously if this is your first run it will be empty. You can add a new target from the right-click context menu of the root node labeled "Available Targets". The right-click context menu for individual targets allow you to delete the target, add a tag under the target as well as load the hits from all tags under the target into the data exploration pane. The right-click context menu for individual tags exposes a number of features:
  • 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.
The PIDA modules list control displays the list of loaded PIDA modules as well their individual function and basic block counts. Prior to attaching to your target you must select and load at least one PIDA module. During the code coverage phase, the PIDA module is referenced for setting breakpoints on functions and/or basic blocks. A PIDA module can be removed from the list through a right-click context menu.

Data Exploration

The data exploraton pane is broken into three sections. The first section is propogated when you load or append hits from the Data Sources column. Each hit is displayed in a scrollable list box. Selecting one of the line items displays, if available, the context data associated with that hit in the Dereferenced Data text control. In between the list and text controls there are two progress bars that represent the total code coverage based on the number of individually hit basic blocks and functions listed in the exploration pane against the number of total basic blocks and functions across all loaded PIDA modules.

Data Capture

Once you have a tag selected for stalking, any appropriate filters applied and your target PIDA modules loaded, the next step is to actually attach to and stalk your target. Hit the Retrieve List button to display an up to date process list, newer processes are listed at the bottom. Select your target process for attaching or browse to your target process for loading, next select your coverage depth. Select Functions to monitor and track which functions are executed within your target or select Basic Blocks to further scrutinize the individual basic blocks executed. The Restore BPs checkbox controls whether or not to restore breakpoints after they have been hit. If you are only interested in what code was executed in your target, then leave the option disabled. Alternatively, if you are interested in both what was executed and the order in which it was executed, then you should enable the option. The Heavy checkbox controls whether or not pstalker will save context data at each recorded hit. Disable this option for increased speed. Uncheck the Unhandled Only check box to receive notification of debug exception events even if the debuggee is capable of correctly handling them. Finally, with all your options set and your target process selected hit the Attach and Start Tracking button to begin code coverage. Watch the log window for run-time information.

Limitations

There is one main limitation to this tool that you should be aware of. Specifically, the tool is reliant on the static analysis of the binary provided by IDA then it will fail when IDA makes mistakes. For example, if data is misrepresented as code then bad things can happen when pstalker sets breakpoints on that data. This is the most common reason for failure. Disabling the "Make final pass" analysis kernel option in IDA prior to the auto-analysis will disable the aggressive logic that makes these types of errors. However, your overall analysis will also suffer. Furthermore, packed or self-modifying code can not be traced currently.