Documentation consolidation & improvements

52ece9a0 · Luke Macken · c4bdfc77 · 52ece9a0 · 52ece9a0 · 52ece9a0
Commit 52ece9a0 authored Mar 19, 2012 by Luke Macken
Hide whitespace changes
Inline Side-by-side

Showing with 80 additions and 192 deletions

README.rst README.rst +7 -159

docs/Installing.rst docs/Installing.rst +50 -14

docs/Payloads.rst docs/Payloads.rst +17 -5

docs/index.rst docs/index.rst +6 -14

No files found.
--- a/README.rst
+++ b/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
 ~~~~~~~

--- a/docs/Installing.rst
+++ b/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


-
--- a/docs/Payloads.rst
+++ b/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



--- a/docs/index.rst
+++ b/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