Documentation.

CONTRIBUTORS

@@ -1,14 +1,17 @@
- 395 Aldo Cortesi
+ 485 Aldo Cortesi
   18 Henrik Nordstrom
   13 Thomas Roth
   11 Stephen Altamirano
-   5 András Veres-Szentkirályi
+   6 András Veres-Szentkirályi
+   4 Valtteri Virtanen
    2 alts
+   2 Michael Frister
    2 Mark E. Haase
    2 Heikki Hannikainen
    1 meeee
    1 capt8bit
    1 Yuangxuan Wang
+   1 Ulrich Petri
    1 Rune Halvorsen
    1 Rory McCann
    1 Henrik Nordström

README.mkd

@@ -53,11 +53,17 @@ Requirements
 * [pyasn1](http://pypi.python.org/pypi/pyasn1) 0.1.2 or newer.
 * [urwid](http://excess.org/urwid/) version 0.9.8 or newer.
 * [PIL](http://www.pythonware.com/products/pil/) version 1.1 or newer.
+* [lxml](http://lxml.de/) version 2.3 or newer.
+
+The following auxiliary components may be needed if you plan to hack on
+mitmproxy:
+
 * The test suite uses the [pry](http://github.com/cortesi/pry) unit testing
   library.
 * Rendering the documentation requires [countershape](http://github.com/cortesi/countershape).
 
-__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. 
+__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. Windows is not
+supported at the moment.
 
 You should also make sure that your console environment is set up with the
 following: 

README.txt

@@ -52,11 +52,17 @@ Requirements
 * pyasn1_ 0.1.2 or newer.
 * urwid_  version 0.9.8 or newer.
 * PIL_  version 1.1 or newer.
+* lxml_ version 2.3 or newer.
+
+The following auxiliary components may be needed if you plan to hack on
+mitmproxy:
+
 * The test suite uses the pry_ unit testing
   library.
 * Rendering the documentation requires countershape_.
 
-**mitmproxy** is tested and developed on OSX, Linux and OpenBSD. 
+**mitmproxy** is tested and developed on OSX, Linux and OpenBSD. Windows is not
+supported at the moment.
 
 You should also make sure that your console environment is set up with the
 following: 
@@ -72,6 +78,7 @@ following:
 .. _PyOpenSSL: http://pypi.python.org/pypi/pyOpenSSL
 .. _pyasn1: http://pypi.python.org/pypi/pyasn1
 .. _PIL: http://www.pythonware.com/products/pil/
+.. _lxml: http://lxml.de/
 .. _urwid: http://excess.org/urwid/
 .. _pry: http://github.com/cortesi/pry
 .. _countershape: http://github.com/cortesi/countershape

doc-src/certinstall/android.html

@@ -97,5 +97,7 @@
 (use the _--upstream-cert_ command-line option, or enable it interactively
 using the _o_ shortcut):
 
-    mitmproxy --upstream-cert
+<pre class="terminal">
+mitmproxy --upstream-cert
+</pre>
 

doc-src/index.html

@@ -1,6 +1,7 @@
 
 <ul class="docindex">
     <li><a href="@!urlTo("intro.html")!@">Introduction</a></li>
+    <li><a href="@!urlTo("install.html")!@">Installation</a></li>
     <li><a href="@!urlTo("mitmproxy.html")!@">mitmproxy</a></li>
     <li><a href="@!urlTo("mitmdump.html")!@">mitmdump</a></li>
     <li>Features</li>

doc-src/index.py

@@ -68,6 +68,7 @@ def example(s):
 pages = [
     Page("index.html", "docs"),
     Page("intro.html", "Introduction"),
+    Page("install.html", "Installation"),
     Page("mitmproxy.html", "mitmproxy"),
     Page("mitmdump.html", "mitmdump"),
     Page("clientreplay.html", "Client-side replay"),

doc-src/install.html

@@ -0,0 +1,57 @@
+
+## Using Pip 
+
+The preferred way to install mitmproxy is to use
+[pip](http://pypi.python.org/pypi/pip). A single command will install the
+latest release of mitmproxy, along with all its dependencies:
+
+<pre>
+sudo pip install mitmproxy
+</pre>
+
+
+## From Source
+
+- When installing from source, you will need to install the
+[dependencies](@!urlTo("intro.html")!@) by hand. 
+- Then run the following command from the base of the source distribution:
+
+<pre>
+sudo python setup.py install
+</pre>
+
+
+## OSX
+
+- Make sure that XCode is installed from the App Store, and that the
+command-line tools have been downloaded (XCode/Preferences/Downloads).
+- Install __pip__ using the following command:
+
+<pre>
+sudo easy_install pip
+</pre>
+
+- Now use __pip__ to set up the dependencies and do the install:
+
+<pre>
+sudo pip install mitmproxy
+</pre>
+
+This procedure may vary if, for instance, you've installed Python from an
+external source like [homebrew](http://mxcl.github.com/homebrew/). In that
+case, the easiest way to proceed is to first install __easy_install__, then
+continue as above.
+
+There are a few bits of customization you might want to do to make mitmproxy
+comfortable to use. At the moment, mitmproxy's color scheme is optimized for a
+dark background terminal, so you probably want to change the default. You can
+use the OSX <b>open</b> program to create a simple and effective
+<b>~/.mailcap</b> file to view HTTP bodies:
+
+<pre>
+application/*; /usr/bin/open -Wn %s
+audio/*; /usr/bin/open -Wn %s
+image/*; /usr/bin/open -Wn %s
+video/*; /usr/bin/open -Wn %s
+</pre>
+

doc-src/replacements.html

@@ -43,7 +43,9 @@
 replacement hook specifier that lets you load the replacement text from a file.
 So, you might start __mitmdump__ as follows:
 
-    mitmdump --replace-from-file :~q:foo:~/xss-exploit
+<pre class="terminal">
+mitmdump --replace-from-file :~q:foo:~/xss-exploit
+</pre>
 
 This will load the replacement text from the file __~/xss-exploit__.
 

todo

@@ -3,18 +3,20 @@ hacking on mitmproxy. Drop me a line (aldo@corte.si) if you want to tackle any
 of these and need some pointers.
 
 Targeted for 0.9:
+    - White-background colorscheme
+    - Extra content view modules: CSS indenter, Flash SWF info extractor
     - Upstream proxy support.
     - Follow mode to keep most recent flow in view
-    - Rewrite the core to be asynchronous. I've done some research, and
-    although it's a bit of a bloated monster, it looks like Twisted is the way
-    to go.
     - Verbose view to show timestamps
     - Search within requests/responses
     - Transparent proxy support
     - Ordering a-la mutt's "o" shortcut
 
 
-Further ideas:
+Future:
+    - Rewrite the core to be asynchronous. I've done some research, and
+    although it's a bit of a bloated monster, it looks like Twisted is the way
+    to go.
     - Add some "workspace" features to mitmproxy:
         - Flow comments
         - Copying/duplicating flows