Skip to content

Commit

Permalink
More tweaks to the repo layout, and some readme updates
Browse files Browse the repository at this point in the history
  • Loading branch information
lmacken committed Mar 14, 2012
1 parent d7b460d commit 8fa95e6
Show file tree
Hide file tree
Showing 4 changed files with 25 additions and 157 deletions.
1 change: 0 additions & 1 deletion AUTHORS
@@ -1,2 +1 @@
Luke Macken <lmacken@redhat.com>
David Malcolm <dmalcolm@redhat.com>
4 changes: 2 additions & 2 deletions MANIFEST.in
@@ -1,4 +1,4 @@
include LICENSE
include README.rst

graft pyrasite
include pyrasite-gui
graft js
169 changes: 16 additions & 153 deletions README.rst
@@ -1,167 +1,32 @@
pyrasite
========
pyrasite-gui
============

.. split here
Pyrasite lets you to inject arbitrary code into an unaltered running Python
process.

It also contains a graphical interface that makes it easy to monitor and
introspect running processes.
A graphical interface that lets you easily analyze and introspect unaltered
running Python processes.

Requirements
~~~~~~~~~~~~

- gdb (https://www.gnu.org/s/gdb) (version 7.3+)
- python-gobject-dev (on debian or ubuntu: apt-get install python-gobject-dev)
- Cython (http://cython.org)
- meliae (https://launchpad.net/meliae)
- easy_install/pip may not work for this install. If not, use the tarball from the distribution website

Download
~~~~~~~~

Download the latest stable release from PyPi: http://pypi.python.org/pypi/pyrasite

::

easy_install pyrasite

Grab the latest source by running:

::

git clone git://git.fedorahosted.org/git/pyrasite

You can also fork pyrasite on GitHub: http://github.com/lmacken/pyrasite

pyrasite-gui
~~~~~~~~~~~~
- Pyrasite (https://github.com/lmacken/pyrasite)
- PyGObject3 Introspection bindings
- Fedora: pygobject3
- Ubuntu: python-gobject-dev
- Arch: python2-gobject
- Cython (http://cython.org)
- meliae (https://launchpad.net/meliae)
- easy_install/pip may not work for this install. If not, use the tarball
from the distribution website

.. image:: http://lewk.org/img/pyrasite/pyrasite-info.png

API
~~~

::

from pyrasite.inject import CodeInjector

ci = CodeInjector(p.pid)
ci.inject('payloads/helloworld.py')


Payloads
~~~~~~~~

Reverse Python Shell
--------------------

This lets you easily introspect or alter any objects in your running process.


::

$ python
>>> x = 'foo'

::

$ pyrasite <PID> payloads/reverse_python_shell.py
$ nc -l localhost 9001
Python 2.7.1 (r271:86832, Apr 12 2011, 16:15:16)
[GCC 4.6.0 20110331 (Red Hat 4.6.0-2)]
Type 'quit' to exit.
>>> print x
foo
>>> globals()['x'] = 'bar'


Viewing the largest objects in your process
-------------------------------------------

This payload uses `meliae <https://launchpad.net/meliae>`_ to dump all of the objects in your process to an `objects.json` file (currently dumped in the working directory of your process).

::

$ pyrasite <PID> payloads/dump_memory.py


Pyrasite also provides a tool to view the values of largest objects in your process.


::

$ pyrasite-memory-viewer <PID> objects.json


.. image:: http://lewk.org/img/pyrasite-memory-viewer.png


Reverse Shell
-------------

::

$ pyrasite <PID> payloads/reverse_shell.py
$ nc -l localhost 9001
Linux tomservo 2.6.40.3-0.fc15.x86_64 #1 SMP Tue Aug 16 04:10:59 UTC 2011 x86_64 x86_64 x86_64 GNU/Linux
Type 'quit' to exit.
% ls


Call Graph
----------

Pyrasite comes with a payload that generates an image of your processes call
graph using `pycallgraph <http://pycallgraph.slowchop.com>`_.

::

$ pyrasite <PID> payloads/start_callgraph.py
$ pyrasite <PID> payloads/stop_callgraph.py

The callgraph is then generated using `graphviz <http://www.graphviz.org>`_ and
saved to `callgraph.png`. You can see an example callgraph `here <http://pycallgraph.slowchop.com/pycallgraph/wiki/RegExpExample>`_.


Dumping modules, thread stacks, and forcing garbage collection
--------------------------------------------------------------

::

payloads/dump_modules.py
payloads/dump_stacks.py
payloads/force_garbage_collection.py

Additional installation notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mac OS X
--------

If you don't want to override Apple's default gdb, install the latest version of gdb with a prefix (e.g. gnu)

::

$ ./configure --program-prefix=gnu
$ pyrasite <PID> payloads/reverse_python_shell.py --prefix="gnu"

Ubuntu
------

Since version 10.10, Ubuntu ships with a `controversial patch <https://lkml.org/lkml/2010/6/16/421>`_ that restricts the scope of ptrace, which can be disabled by running:

::

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Arch Linux
----------

You can install pyrasite from the `Arch User Repository <https://aur.archlinux.org/packages.php?ID=57604>`_ If you want python debugging symbols, you may have to self compile python2.
.. image:: http://lewk.org/img/pyrasite/pyrasite-stacks.png

.. image:: http://lewk.org/img/pyrasite/pyrasite-objects.png

.. image:: http://lewk.org/img/pyrasite/pyrasite-callgraph.png

Mailing List
~~~~~~~~~~~~
Expand All @@ -180,5 +45,3 @@ Luke Macken <lmacken@redhat.com>

.. image:: http://api.coderwall.com/lmacken/endorsecount.png
:target: http://coderwall.com/lmacken

David Malcolm <dmalcolm@redhat.com>
8 changes: 7 additions & 1 deletion setup.py
Expand Up @@ -6,13 +6,19 @@
long_description = f.read().split('split here')[1]
f.close()

try:
from gi.repository import GLib, GObject, Pango, Gtk, WebKit
except ImportError:
print "Unable to find pygobject3. Please install the 'pygobject3' "
print "package on Fedora, or 'python-gobject-dev on Ubuntu."
sys.exit(1)
try:
from meliae import version_info
except ImportError:
print "We require meliae to be installed."
exit(1)

setup(name='pyrasite',
setup(name='pyrasite-gui',
version=version,
description="Inject code into a running Python process",
long_description=long_description,
Expand Down

0 comments on commit 8fa95e6

Please sign in to comment.