Parse gdb machine interface string output and return structured data types (Python dicts) that are JSON serializable. Useful for writing the backend to a gdb frontend. For example, gdbgui uses pygdbmi on the backend.
Also implements a class to control gdb, GdbController
, which allows
programmatic control of gdb using Python, which is also useful if
creating a front end.
To get machine
interface
output from gdb, run gdb with the --interpreter=mi2
flag.
pip install pygdbmi
Ubuntu 14.04+
macOS Note: macOS users must also codesign gdb. Follow [these instructions](http://andresabino.com/2015/04/14/codesign-gdb-on-mac-os-x-yosemite-10-10-2/). This will fix the error please check gdb is codesigned - see taskgated(8).
gdb 7.7+
gdb mi defines a syntax for its output that is suitable for machine readability and scripting: example output:
-> -break-insert main <- ^done,bkpt={number="1",type="breakpoint",disp="keep", enabled="y",addr="0x08048564",func="main",file="myprog.c", fullname="/home/myprog.c",line="68",thread-groups=["i1"], times="0"} <- (gdb)
Use pygdbmi.gdbmiparser.parse_response
to turn that string output
into a JSON serializable dictionary
from pygdbmi import gdbmiparser from pprint import pprint response = gdbmiparser.parse_response('^done,bkpt={number="1",type="breakpoint",disp="keep", enabled="y",addr="0x08048564",func="main",file="myprog.c",fullname="/home/myprog.c",line="68",thread-groups=["i1"],times="0"') pprint(response) > {'message': 'done', 'payload': {'bkpt': {'addr': '0x08048564', 'disp': 'keep', 'enabled': 'y', 'file': 'myprog.c', 'fullname': '/home/myprog.c', 'func': 'main', 'line': '68', 'number': '1', 'thread-groups': ['i1'], 'times': '0', 'type': 'breakpoint'}}, 'type': 'result'}
But how do you get the gdb output into Python in the first place? If you
want, pygdbmi
also has a class to control gdb as subprocess. You can
write commands, and get structured output back:
from pygdbmi.gdbcontroller import GdbController from pprint import pprint # Start gdb process gdbmi = GdbController() # Load binary a.out and get structured response response = gdbmi.write('-file-exec-file a.out') pprint(response) [{'message': u'thread-group-added', 'payload': {u'id': u'i1'}, 'type': 'notify'}, {'message': u'done', 'payload': None, 'type': 'result'}]
Now do whatever you want with gdb. All gdb commands, as well as gdb
machine interface
commands
are acceptable. gdb mi commands give better structured output that is
machine readable, rather than gdb console output. mi commands begin with
a -
.
response = gdbmi.write('-break-insert main') response = gdbmi.write('break main') response = gdbmi.write('-exec-run') response = gdbmi.write('run') # normal gdb command is okay too response = gdbmi.write('-exec-next') response = gdbmi.write('next') response = gdbmi.write('-exec-continue') response = gdbmi.write('continue') response = gdbmi.exit()
Each parsed gdb response consists of a list of dictionaries. Each
dictionary has keys message
, payload
, token
, and type
.
message
contains a textual message from gdb, which is not always present. When missing, this isNone
.payload
contains the content of gdb's output, which can contain any of the following:dictionary
,list
,string
. This too is not always present, and can beNone
depending on the response.token
If an input command was prefixed with a (optional) token then the corresponding output for that command will also be prefixed by that same token. This field is only present for pygdbmi output typesnofity
andresult
. When missing, this isNone
.
The type
is defined based on gdb's various mi output record
types,
and can be
- result - the result of a gdb command, such as
done
,running
,error
, etc. - notify - additional async changes that have occurred, such as breakpoint modified
- console - textual responses to cli commands
- log - debugging messages from gdb's internals
- output - output from target
- target - output from remote target
- done - when gdb has finished its output
Set up a new virtual environment, then clone this repo and run
pip install -r requirements.txt
and pip install -r dev_requirements.txt
.
Confirm unit tests are working with
make test
, then begin development.
Update unit tests as necessary at pygdbmi/tests/test\_app.py
.
- gdbgui implements a browser-based frontend to gdb, using pygdbmi on the backend
- PINCE is a gdb frontend that aims to provide a reverse engineering tool and a reusable library focused on games. It uses pygdbmi to parse gdb/mi based output for some functions
- avatar² is an orchestration framework for reversing and analysing firmware of embedded devices. It utilizes pygdbmi for internal communication to different analysis targets.
- Know of another project? Create a PR and add it here.