python-ptrace
*************

python-ptrace is a debugger using ptrace (Linux, BSD and Darwin system
call to trace processes) written in Python.

* python-ptrace documentation

* python-ptrace at GitHub

* python-ptrace at the Python Cheeseshop (PyPI)

python-ptrace is an opensource project written in Python under GNU
GPLv2 license.


Features
========

* High level Python object API : PtraceDebugger and PtraceProcess

* Able to control multiple processes: catch fork events on Linux

* Read/write bytes to arbitrary address: take care of memory
  alignment and split bytes to cpu word

* Execution step by step using ptrace_singlestep() or hardware
  interruption 3

* Can use distorm disassembler

* Dump registers, memory mappings, stack, etc.

* Syscall tracer and parser (strace.py command)

Status:

* Supported operating systems: Linux, FreeBSD, OpenBSD

* Supported architectures: x86, x86_64 (Linux), PPC (Linux), ARM
  (Linux EAPI)

Missing features:

* Symbols: it's not possible to break on a function or read a
  variable value

* No C language support: debugger shows assembler code, not your C
  (C++ or other language) code!

* No thread support


Table of Contents
=================

* Install python-ptrace

  * Linux packages

  * Install from source

  * cptrace

  * Run tests

* python-ptrace usage

  * Hello World

  * API

* Trace system calls (syscalls)

  * PtraceSyscall

  * strace.py

* gdb.py

  * Some commands

  * Features

  * Screenshot

* python-ptrace process events

  * Process events

  * Wait for any process event

  * Wait for a specific process events

* python-ptrace signal handling

  * Introduction

  * Examples

  * Examples

  * Source code

* cptrace Python module

  * Example

* Authors

  * Contributors

  * Thanks

* Changelog

  * python-ptrace 0.9.3 (2017-09-19)

  * python-ptrace 0.9.2 (2017-02-12)

  * python-ptrace 0.9.1 (2016-10-12)

  * python-ptrace 0.9 (2016-04-23)

  * python-ptrace 0.8.1 (2014-10-30)

  * python-ptrace 0.8 (2014-10-05)

  * python-ptrace 0.7 (2013-03-05)

  * python-ptrace 0.6.6 (2013-12-16)

  * python-ptrace 0.6.5 (2013-06-06)

  * python-ptrace 0.6.4 (2012-02-26)

  * python-ptrace 0.6.3 (2011-02-16)

  * python-ptrace 0.6.2 (2009-11-09)

  * python-ptrace 0.6.1 (2009-11-07)

  * python-ptrace 0.6 (2009-02-13)

  * python-ptrace 0.5 (2008-09-13)

  * python-ptrace 0.4.2 (2008-08-28)

  * python-ptrace 0.4.1 (2008-08-23)

  * python-ptrace 0.4.0 (2008-08-19)

* TODO

  * Main tasks

  * Minor tasks


Links
=====


Project using python-ptrace
---------------------------

* Fusil the fuzzer


python-ptrace announces
-----------------------

* fuzzing mailing list

* reverse-engineering.net


ptrace usage
------------

* Sandboxing: Plash


Similar projects
----------------

* vtrace: Python library (Windows and Linux) supporting threads

* subterfuge by Mike Coleman: Python library (Linux): contains
  Python binding of ptrace written in C for Python 2.1/2.2. It doesn't
  work with Python 2.5 (old project, not maintained since 2002)

* strace program (Linux, BSD)

* ltrace program (Linux)

* truss program (Solaris and BSD)

* pytstop by Philippe Biondi: debugger similar to gdb but in very
  alpha stage (e.g. no disassembler), using ptrace Python binding
  written in C (from subterfuge)

* strace.py by Philippe Biondi

* Fenris: suite of tools suitable for code analysis, debugging,
  protocol analysis, reverse engineering, forensics, diagnostics,
  security audits, vulnerability research

* PyDBG: Windows debugger written in pure Python


Interesting articles
--------------------

* (fr) Surveiller les connexions avec auditd (2007)

* Playing with ptrace() for fun and proﬁt (2006)

* PTRACE_SETOPTIONS tests (2005)

* Process Tracing Using Ptrace (2002)
