Begin to flesh out and refactor docs.

README.mkd

@@ -1,35 +1,26 @@
-__mitmproxy__ is an interactive SSL-capable intercepting HTTP proxy. It lets
-you to observe, modify and replay requests and responses on the fly. The
-underlying library that mitmproxy is built on can also be used to do these
-things programmatically. 
 
-By default, mitmproxy starts up with a mutt-like interactive curses interface -
+__mitmproxy__ and __mitmdump__ are SSL-capable, intercepting HTTP proxies.
-the built-in help page (which you can view by pressing "?") will tell you
+
-everything you need to know. Note that requests and responses are stored
+__mitmproxy__ provides a curses interface that allows traffic to be inspected
-in-memory until you delete them, so leaving mitmproxy running indefinitely or
+and edited on the fly.
-requesting very large amounts of data through it is a bad idea.
+
+__mitmdump__ is a tcpdump-like tool for HTTP.
 
 
-SSL
+Capabilities
----
+============
 
-The first time mitmproxy is started, it will generate a bogus SSL certificate
+- Intercept HTTP requests and responses and modify them on the fly.
-authority (the default location is ~/.mitmproxy/ca.pem). This CA is used to
+- Save complete HTTP conversations for later replay and analysis.
-generate certificates for SSL requests on-the-fly. To avoid the hassle of
+- Client replay to replay the client-side of an HTTP conversation.
-having to accept these certificates individually, you can add the certificate
+- Server replay replays the HTTP responses of a previously recorded server.
-authority to your browser or globally to your system.
+- Make scripted changes to HTTP traffic using a simple Python API. 
+- Dummy SSL certificate authority creates interception certificates on the fly.
 
 
-Documentation
--------------
-
-A rendered version of the docs for the latest release can be found here:
-
-http://corte.si/projects.html
-
 
 Download
---------
+========
 
 Releases can be found here: http://corte.si/projects.html
 
@@ -37,7 +28,7 @@ Source is hosted here: http://github.com/cortesi/mitmproxy
 
 
 Requirements
-------------
+============
 
 * A recent [Python](http://www.python.org) interpreter.
 * SSL certificates are generated using [openssl](http://www.openssl.org/)
@@ -53,5 +44,3 @@ following:
 * PAGER environment variable to determine the external pager.
 * Appropriate entries in your mailcap files to determine external
   viewers for request and response contents.
-
-

doc-src/certinstall/firefox.html

@@ -0,0 +1,15 @@
+
+### 1: Open preferences, click on "Advanced", then select"Encryption":
+
+<img src="@!urlTo('firefox3.jpg')!@"/>
+
+### 2: Click "View Certificates", "Import", and select the certificate file: 
+
+<img src="@!urlTo('firefox3-import.jpg')!@"/>
+
+### 3: Tick "Trust this CS to identify web sites", and click "Ok":
+
+<img src="@!urlTo('firefox3-trust.jpg')!@"/>
+
+You should now see the mitmproxy certificate listed in the Authorities tab.
+

doc-src/certinstall/index.py

@@ -0,0 +1,10 @@
+from countershape import Page
+
+pages = [
+    Page("firefox.html", "Firefox"),
+    Page("chrome.html", "Chrome"),
+    Page("safari.html", "Safari"),
+    Page("ie.html", "Internet Explorer"),
+    Page("windows7.html", "Windows 7"),
+    Page("ios.html", "IOS"),
+]

doc-src/index.html

@@ -1,25 +1,26 @@
 
 
 * [Introduction](@!urlTo("intro.html")!@)
+* [mitmproxy](@!urlTo("/mitmproxy.html")!@)
+* [mitmdump](@!urlTo("/mitmdump.html")!@)
+* [Client script API](@!urlTo("scripts.html")!@)
+* [libmproxy](@!urlTo("library.html")!@)
+* [SSL](@!urlTo("/ssl.html")!@)
+    * Browser certificate installation: 
+        * [Firefox](@!urlTo("certinstall/firefox.html")!@#firefox)
+        * [Chrome](@!urlTo("certinstall/chrome.html")!@#chrome)
+        * [Safari](@!urlTo("certinstall/safari.html")!@#safari)
+        * [Internet Explorer](@!urlTo("certinstall/ie.html")!@#ie)
+    * System-wide certificate installation:
+        * [Windows 7](@!urlTo("certinstall/windows7.html")!@#windows7)
+        * [iPhone/iPad](@!urlTo("certinstall/ios.html")!@#ios)
 * Tutorials
     * Client replay: a 30 second example
-    * Scripting: On-the-fly modifications to HTTP conversations
+    * Scripting: On-the-fly modifications to HTTP conversations [coming soon]
-    * Breaking iPhone apps for fun and profit
+    * Sticky cookies  [coming soon]
-* Reference
+    * Breaking iPhone apps for fun and profit [coming soon]
-    * [mitmproxy - HTTP Swiss Army Knife](@!urlTo("/mitmproxy.html")!@)
-    * [mitmdump - A tcpdump-like tool for HTTP](@!urlTo("/mitmdump.html")!@)
-    * [Client scripts](@!urlTo("scripts.html")!@)
-    * [libmproxy](@!urlTo("library.html")!@) - Using the mitmproxy library
-* Installing mitmproxy's SSL certificate
-    * [Firefox](@!urlTo("ssl.html")!@#firefox)
-    * [Chrome](@!urlTo("ssl.html")!@#chrome)
-    * [Safari](@!urlTo("ssl.html")!@#safari)
-    * [IE8](@!urlTo("ssl.html")!@#ie)
-    * System-wide installation:
-        * [Windows 7](@!urlTo("ssl.html")!@#windows7)
-        * [iPhone/iPad](@!urlTo("ssl.html")!@#ios)
 * [FAQ](@!urlTo("faq.html")!@)
-* [administrivia](@!urlTo("admin.html")!@)
+* [Administrivia](@!urlTo("admin.html")!@)
 
 
 

doc-src/ssl.html

@@ -1,41 +1,34 @@
 
-# Browsers
+SSL
+===
 
-<a name="firefox"></a>
+The first time __mitmproxy__ or __mitmdump__ is started, a dummy SSL
-## Firefox 3.x
+certificate authority is generated (the default location is
+~/.mitmproxy/ca.pem). This dummy CA is used to generate dummy certificates for
+SSL interception on-the-fly. Since your browser won't trust the __mitmproxy__
+dummy CA out of the box (and rightly so), so you will see an SSL cert warning
+every time you visit a new SSL domain through __mitmproxy__. When you're
+testing a single site, just accepting the bogus SSL cert manually is not too
+much of a hassle, but there are a number of cases where you will want to
+configure your testing system or browser to trust __mitmproxy__:
 
-### 1: Open preferences, click on "Advanced", then select"Encryption":
+- If you are testing non-browser software that checks SSL cert validiy.
-
+- You are testing an app that makes non-interactive (JSONP, script src, etc.)
-<img src="@!urlTo('firefox3.jpg')!@"/>
+requests to SSL resources. Another workaround in this case is to manually visit
-
+the page through the browser, and add a certificate exception.
-### 2: Click "View Certificates", "Import", and select the certificate file: 
+- You just don't want to deal with the hassle of continuously adding cert
-
+exceptions.
-<img src="@!urlTo('firefox3-import.jpg')!@"/>
-
-### 3: Tick "Trust this CS to identify web sites", and click "Ok":
-
-<img src="@!urlTo('firefox3-trust.jpg')!@"/>
-
-You should now see the mitmproxy certificate listed in the Authorities tab.
 
 
-<a name="chrome"></a>
+Installing the mitmproxy CA
-## Chrome
+===========================
-
-<a name="safari"></a>
-## Safari
-
-<a name="ie"></a>
-## Internet Explorer 8
-
-
-# Global installation
-
-<a name="windows"></a>
-## Windows 7
-
-<a name="ios"></a>
-## iPhone/iPad
-
 
+* Browser certificate installation: 
+    * [Firefox](@!urlTo("certinstall/firefox.html")!@#firefox)
+    * [Chrome](@!urlTo("certinstall/chrome.html")!@#chrome)
+    * [Safari](@!urlTo("certinstall/safari.html")!@#safari)
+    * [Internet Explorer](@!urlTo("certinstall/ie.html")!@#ie)
+* System-wide certificate installation:
+    * [Windows 7](@!urlTo("certinstall/windows7.html")!@#windows7)
+    * [iPhone/iPad](@!urlTo("certinstall/ios.html")!@#ios)