Documentation consolidation & improvements

README.rst

@@ -6,173 +6,21 @@ pyrasite
 Pyrasite lets you to inject arbitrary code into an unaltered running Python
 process.
 
-Requirements
-~~~~~~~~~~~~
-
-  - gdb (https://www.gnu.org/s/gdb) (version 7.3+)
-
-Download
-~~~~~~~~
-
-Download the latest stable release from PyPi: http://pypi.python.org/pypi/pyrasite
-
-::
-
-    pip install pyrasite
-
-You can also run the latest pyrasite from source:
-
-::
+:documentation: http://pyrasite.com
+:download: http://pypi.python.org/pypi/pyrasite
+:source: http://github.com/lmacken/pyrasite
+:mailing list: https://fedorahosted.org/mailman/listinfo/pyrasite
+:jenkins: http://ci.csh.rit.edu/view/Pyrasite
+:irc: #pyrasite on Freenode
 
-    git clone git://github.com/lmacken/pyrasite.git
-    cd pyrasite
-    python -m pyrasite.main
 
 pyrasite-gui
 ~~~~~~~~~~~~
 
 The gui has been moved into it's own repository: https://github.com/lmacken/pyrasite-gui
 
-.. image:: http://lewk.org/img/pyrasite/pyrasite-info.png
-
-API
-~~~
-
-::
-
-    from pyrasite.inject import CodeInjector
-
-    ci = CodeInjector(p.pid)
-    ci.inject('pyrasite/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> pyrasite/payloads/reverse_python_shell.py
-    $ nc -l 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).
-
-We recommend using python-meliae from your OS distribution, if available. If it
-is not, you will need to first install Cython, and then meliae seperately. If
-pip/easy_install does not work, you may need to use the tarball from the
-upstream website.
-
-::
-
-    $ pyrasite <PID> pyrasite/payloads/dump_memory.py
-
-
-Pyrasite also provides a tool to view the values of largest objects in your
-process. This requires `urwid <http://pypi.python.org/pypi/urwid>`_ to be
-installed.
-
-::
-
-    $ pyrasite-memory-viewer <PID> objects.json
-
-
-.. image:: http://lewk.org/img/pyrasite-memory-viewer.png
-
-
-Reverse Shell
--------------
-
-::
-
-    $ pyrasite <PID> pyrasite/payloads/reverse_shell.py
-    $ nc -l 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> pyrasite/payloads/start_callgraph.py
-    $ pyrasite <PID> pyrasite/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
---------------------------------------------------------------
-
-::
-
-    pyrasite/payloads/dump_modules.py
-    pyrasite/payloads/dump_stacks.py
-    pyrasite/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> pyrasite/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.
-
-
-
-Mailing List
-~~~~~~~~~~~~
-
-https://fedorahosted.org/mailman/listinfo/pyrasite
-
-IRC
-~~~
+.. image:: http://lewk.org/img/pyrasite/pyrasite-info-thumb.png
 
-#pyrasite on Freenode.
 
 Authors
 ~~~~~~~

docs/Installing.rst

@@ -9,13 +9,41 @@ Core
 
  * `gdb <https://www.gnu.org/s/gdb>`_ (version 7.3+)
 
-Optional (needed for the GUI)
------------------------------
+GUI
+---
 
- * python-debuginfo
- * `meliae <https://launchpad.net/meliae>`_
- * `pycallgraph <http://pycallgraph.slowchop.com>`_
- * `psutil <http://code.google.com/p/psutil>`_
+ - `Pyrasite <https://github.com/lmacken/pyrasite>`_
+ - python-debuginfo (needed for live object inspection)
+ - PyGObject3 Introspection bindings
+
+   - Fedora: pygobject3
+   - Ubuntu: python-gobject-dev
+   - Arch: python2-gobject
+
+ - WebKitGTK3
+
+   - Fedora: webkitgtk3
+   - Ubuntu: gir1.2-webkit-3.0
+   - Arch: libwebkit3
+
+ - `meliae <https://launchpad.net/meliae>`_
+   - easy_install/pip may not work for this install. If not, use the tarball from the distribution website. You may need to install `Cython <http://cython.org>`_ in order to get meliae to build.
+
+   - Fedora: python-meliae
+   - Ubuntu: python-meliae
+   - Arch: python2-meliae
+
+ - `pycallgraph <http://pycallgraph.slowchop.com>`_
+
+   - Fedora: python-pycallgraph
+   - Ubuntu: python-pycallgraph
+   - Arch: python2-pycallgraph
+
+ - `psutil <http://code.google.com/p/psutil>`_
+
+   - Fedora: python-psutil
+   - Ubuntu: python-psutil
+   - Arch: python2-psutil
 
 Download
 ~~~~~~~~
@@ -24,20 +52,25 @@ Download the latest stable release from PyPi: http://pypi.python.org/pypi/pyrasi
 
 ::
 
-    easy_install pyrasite
+    pip install pyrasite
 
-Grab the latest source by running:
+Running from git
+~~~~~~~~~~~~~~~~
 
 ::
 
-    git clone git://git.fedorahosted.org/git/pyrasite
+    git clone git://github.com/lmacken/pyrasite.git
+    cd pyrasite
+    python -m pyrasite.main
+
+.. note::
 
-You can also fork pyrasite on GitHub: http://github.com/lmacken/pyrasite
+   If you're on Python 2.4, you can run pyrasite by doing
+   ``PYTHONPATH=$(pwd) python pyrasite/main.py``
 
 Additional installation notes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
 Fedora
 ------
 
@@ -48,7 +81,7 @@ pyrasite on Fedora by doing the following:
 
    sudo yum -y install python-meliae python-devel python-psutil pygobject3 graphviz python-virtualenv git-core gcc
    sudo yum -y --enablerepo=\*-debuginfo install python-debuginfo
-   git clone -b develop git://git.fedorahosted.org/git/pyrasite
+   git clone -b develop git://github.com/lmacken/pyrasite.git
    cd pyrasite
    virtualenv [--system-site-packages if on F16+] env
    source env/bin/activate
@@ -61,7 +94,6 @@ If you're using Fedora 17 or later, you'll need to disable an SELinux boolean to
 
    sudo setsebool -P deny_ptrace=off
 
-
 Mac OS X
 --------
 
@@ -72,6 +104,11 @@ If you don't want to override Apple's default gdb, install the latest version of
     $ ./configure --program-prefix=gnu
     $ pyrasite <PID> payloads/reverse_python_shell.py --prefix="gnu"
 
+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.
+
 Ubuntu
 ------
 
@@ -82,4 +119,3 @@ Since version 10.10, Ubuntu ships with a `controversial patch <https://lkml.org/
     echo 0 > /proc/sys/kernel/yama/ptrace_scope
 
 
-

docs/Payloads.rst

@@ -18,10 +18,12 @@ This lets you easily introspect or alter any objects in your running process.
 ::
 
     $ pyrasite <PID> pyrasite/payloads/reverse_python_shell.py
+
+::
+
     $ nc -l 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'
@@ -29,7 +31,14 @@ This lets you easily introspect or alter any objects in your running process.
 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).
+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).
+
+We recommend using python-meliae from your OS distribution, if available.
+If it is not, you will need to first install Cython, and then meliae
+seperately. If pip/easy_install does not work, you may need to use the
+tarball from the upstream website.
 
 .. literalinclude:: ../pyrasite/payloads/dump_memory.py
    :language: python
@@ -40,8 +49,9 @@ This payload uses `meliae <https://launchpad.net/meliae>`_ to dump all of the ob
     $ pyrasite <PID> pyrasite/payloads/dump_memory.py
 
 
-Pyrasite also provides a command-line tool to view the values of largest
-objects in your process.
+Pyrasite also provides a tool to view the values of largest objects in your
+process. This requires `urwid <http://pypi.python.org/pypi/urwid>`_ to be
+installed.
 
 
 ::
@@ -62,9 +72,11 @@ Reverse Shell
 ::
 
     $ pyrasite <PID> pyrasite/payloads/reverse_shell.py
+
+::
+
     $ nc -l 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
 
 

docs/index.rst

 Welcome to Pyrasite's documentation!
 ====================================
 
-Pyrasite is a module and a set of tools for injecting code into running Python
-programs.
+Pyrasite is a library and a set of tools for injecting code into running
+Python programs.
 
 :download: http://pypi.python.org/pypi/pyrasite
 :source: http://github.com/lmacken/pyrasite
 :mailing list: https://fedorahosted.org/mailman/listinfo/pyrasite
-:jenkins: http://ci.csh.rit.edu/job/pyrasite-py2.7
+:jenkins: http://ci.csh.rit.edu/view/Pyrasite
+:irc: #pyrasite on `Freenode <http://webchat.freenode.net>`_
 
 Contents
 ---------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
 
    Installing
    GUI
    CLI
    Payloads
-
-API
----
-
-.. autosummary::
-
-   pyrasite.CodeInjector
-   pyrasite.ObjectInspector
-   pyrasite.PyrasiteIPC
-   pyrasite.ReverseConnection
+   API