Console Menus
Connectons\MySQL Connect
Establish a console wide connection to your database server. A MySQL connection is required for example in the pstalker and peek modules.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\Set Username
Set your console-wide username which can then be used by any loaded module. The PAIMEIpeek module for example relies on this value to associate recorded actions with individual users.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
Connectons\Save Options
Save the current MySQL, uDraw and PyDbg connection settings as well as the current username to a serialized file on disk. This file is automatically parsed on startup to restore the set values but NOT the actual connections. See the next menu option for a shortcut to restoring connections.Connectons\Restore Connections
Restore console-wide connectivity based on saved settings. Connections to MySQL, uDraw and PyDbg are automatically restored. See the status bar for the connection status.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
The file fuzz module is intended to demonstrate the use of the PaiMei framework for developing fuzzers. It is simple in design and operation but can be very effective at generating and running fuzzer test cases against any target application. The general workflow associated with this tool is broken down into two steps, test case generation and test case execution.Test Case Generation
- Add your source file path to the "Source File Name" input control.
- Add the destination path of the generated files to the "Destination Directory" input control.
- In the "Byte Modifications" sections input the value you would like to use for all byte modifications in the "Hex Bytes" input control.
- The value should begin with a "0x" and be base 16.
- Multiple byte lengths can be used e.g. byte, word, dword.
- Enter the starting file offset to begin modifications in the "Range Start" input control, leave blank to modify from the beginning of the file.
- Enter the ending file offset to stop modifications in the "Range End" input control, leave blank to modify until the end of the file.
- In the "Fuzz" section hit "Generate" to begin generating files.
Test Case Execution
- After generation, the list of test cases should populate the "Fuzz" list box. If you would like to run previously generated, or independently generated, test cases add the path to the "Destination Directory" and click "Refresh List".
- At this moment there is no checking on whether the destination directory contains only desireable test case so be sure to seperate everything accordingly.
- Refreshing the list control will remove any existing test cases.
- Add the path to the target application in the "Program Name" input control.
- Set the desired timeout value in the "Timeout" input box (a good choice for most target is ~5 seconds).
- In the "Fuzz" section hit "Run".
PAIMEIpeek
The peek module is intended to replace the earlier command line version that turned out to be usable only by its author. The primary usage of this tool is for locating "low hanging fruit" vulnerabilities in closed-source Windows software. There are three phases to using the peek tool:Reconnaissance
You must begin by first running the proc_peek_recon_db.py IDA Python script, after IDA has finished its auto-analysis. The script asks for your MySQL server information and then determines / transfers a list of various potentially interesting locations within the binary (I call these "RECON points"). Example locations include discovered inline memcpy()'s, calls to various routines that take format strings and are passed a %s format string token as well as calls to potentially dangerous API such as strcat, strcpy and the like. For the full list, see the source code. It's by no means an exhaustive list in the current release.Capture
With the RECON data in place, load the PAIMEIpeek module, hit "Select Module" and choose the appropriate module name. The list of discovered points will be enumerated in the list control. You can manually add to this list by hitting the "Add RECON Point" button.The "Options" button pops up a dialog where you can specify the same options that the original command line version of this tool provided. The first check box controls whether or not to display context dumps in the log window at run-time. The next check box controls whether or not to hook and log the contents of the packets received by the Winsock recv() and recv_from() API. The next option allows you to specify an output file to store a copy of all log messages to. Finally, the Boron tag field allows you to specify a string to search all context dumps for. Boron tagging is a term coined by Greg Hoglund, you can read more about this concept in the sample chapter Reverse Engineering and Program Understanding from his book Exploiting Software.
With your options set you are now ready to hit the "Peek!" button to select an existing process to attach to or a new process to load. PyDbg is then used to set breakpoints on each of the RECON points and monitor the output. When you are satisfied detach PyDbg from the target by hitting "Stop" (the Peek! button toggles back and forth depending on status). Your captured data is now refreshed into the list control and you are ready for analysis.
Analysis
Selecting a row from the list control fills the "Hits" columns with an entry for every time the selected RECON point was hit. Select one of the entries in the hits column to display the captured data in the "Peek Point Data" text control. Use the TAB, SHIFT-TAB, UP, DOWN, PAGE-UP and PAGE-DOWN keys to quickly navigate the interface.The right-click context menu on the RECON list control allows you to edit, delete or self-assign an individual RECON point. In the edit dialog use the "Status" dropdown to set the state of the selected point. The states are as follows:
- new: No one has looked at this point yet.
- uncontrollable: According to empirical data, we can't influence the data at this point.
- clear: The point was examined thoroughly and determined that no vulnerability was present.
- unsure: More research on this point is necessary.
- vulnerable: This RECON point is in some way involved in an exposed vulnerability.
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:- Create a new target and/or tag. Targets can contain multiple tags and each individual tag contains it's own saved code coverage data.
- Select a tag for staking.
- Load PIDA modules for every .DLL and the .EXE you wish to stalk.
- Launch your target.
- Refresh the process list under the data capture panel and select your target process for attaching or browse to the target process for loading.
- Configure the code coverage options and attach to the selected target.
- Interact with your target while code coverage is being recorded.
- When you are ready, detach from the target and wait for pstalker to export captured items to the database.
- Load the recorded hits to begin exploring your recorded data.
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.
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.