CERT 'exploitable' GNU Debugger (GDB) extension version 1.04
October 4, 2012

===== Requirements =====

Compatible 32-bit or 64-bit Linux 
GDB 7.2 or later
Python 2.6 or later

===== About =====

The CERT 'exploitable' engineering tool is a GDB extension that classifies Linux application bugs by severity. The extension inspects the state of a Linux application that has crashed and outputs a summary of how difficult it might be for an attacker to exploit the underlying software bug to gain control of the system. The extension can be used to prioritize bugs for software developers so that they can address the most severe ones first. 

The extension implements a GDB command called 'exploitable'. The command uses heuristics to describe the exploitability of the state of the application that is currently being debugged in GDB. The command is designed to be used on Linux platforms and versions of GDB that include the GDB Python API. Note that the command will not operate correctly on core file targets at this time.

WARNING: This is an engineering tool. It has not been has not been exhaustively tested, and has not been executed on many flavors of Linux! Please read and understand the classification rules (lib/rules.py) before use and modify the source code to suit your specific testing needs if necessary.

===== Usage =====

Global installation and usage
  1. Copy all files in this directory and its sub-directories to your 
     GDB Python data directory, which is probably /usr/share/gdb/python. 
       ex: sudo cp -r * /usr/share/gdb/python/
     To check your data directory, run gdb -ex "show data-dir"
  2. Import the exploitable file as a module and run a command
       (gdb) python import exploitable
       (gdb) exploitable
Local usage
  1. Copy all files in this directory and its sub-directories to a 
     sub-directory that is accessible from GDB
  2. Source the exploitable file as a script and run a command
       (gdb) source my-exploitable-dir/exploitable.py
       (gdb) exploitable
       
In many cases exploitable makes guesses and calculates values based on GDB's stack unwind. The extension will work best if GDB can find the debug symbols for binaries, especially libc. 

Note that the extension's classification capability is significantly degraded when run in a GDB session with a core file target. When GDB is run against a core file, much of the information that the extension uses for classification is not present via conventional GDB APIs.

===== Testing =====

This project includes test cases (tests/) that can be used as a starting point for testing the 'exploitable' command on new Linux platforms. A Makefile is included. Note that test case filenames generally correspond to the most exploitabile tag that should be applied to the test case, however, because Linux platforms handle errors differently, an exact correspondence will not exist for all of the test cases on most Linux platforms. 

A few unit tests have been implemented in lib/unit_tests.py. unit_tests.py is  meant to be invoked from GDB -- see comments in the file for details.

===== Internals Overview =====

exploitable runs in GDB's Python interpreter (which depends on the Python C API) and uses GDB's Python API. For details, see:
http://sourceware.org/gdb/onlinedocs/gdb/Python-API.html

exploitable iterates over a list of ordered "rules" (lib/rules.py) to generate a Classification (lib/classifier.py). If the state of the application running in GDB matches a rule, exploitable adds a corresponding "tag" to the Classification. The result of an exploitable invocation is a Classification-- either printed to the GDB's stdout or stored to a pickle file, depending on command parameters. 

The entry point for the GDB command is defined in exploitable.py. Iteration over the rules is implemented by a Classifier object (lib/classifier.py). The functions that determine whether a rule matches or not are called "analyzers" (lib/analyzers.py). The state of the application is queried via a set of GDB API wrapper objects and methods (lib/gdb_wrapper.py). A Classification (lib/classifier.py) retains attributes for the "most exploitable" (lowest ordered) tag (matching rule), but it also includes an ordered list of all other matching tags.

Classification rule definitions, located in lib/rules.py, can be re-prioritized by simple cut/paste.
