Docs: replacements, upstream certs.

Also, move reverse proxy command-line flag to -P.

doc-src/replacements.html

@@ -0,0 +1,59 @@
+- command-line: _--replace_, _--replace-from-file_
+- mitmproxy shortcut: _R_
+
+Mitmproxy lets you specify an arbitrary number of patterns that define text
+replacements within flows. Each pattern has 3 components: a filter that defines
+which flows a replacement applies to, a regular expression that defines what
+gets replaced, and a target value that defines what is substituted in.
+
+Replace hooks fire when either a client request or a server response is
+received. Only the matching flow component is affected: so, for example, if a
+replace hook is triggered on server response, the replacement is only run on
+the Response object leaving the Request intact. You control whether the hook
+triggers on the request, response or both using the filter pattern. If you need
+finer-grained control than this, it's simple to create a script using the
+replacement API on Flow components. 
+
+Replacement hooks are extremely handy in interactive testing of applications.
+For instance you can use a replace hook to replace the text "XSS" with a
+complicated XSS exploit, and then "inject" the exploit simply by interacting
+with the application through the browser. When used with tools like Firebug and
+mitmproxy's own interception abilities, replacement hooks can be an amazingly
+flexible and powerful feature. 
+
+
+## On the command-line
+
+The replacement hook command-line options use a compact syntax to make it easy
+to specify all three components at once. The general form is as follows:
+
+    /patt/regex/replacement
+
+Here, __patt__ is a mitmproxy filter expression, __regex__ is a valid Python
+regular expression, and __replacement__ is a string literal. The first
+character in the expression (__/__ in this case) defines what the separation
+character is. Here's an example of a valid expression that replaces "foo" with
+"bar" in all requests:
+
+    :~q:foo:bar
+
+In practice, it's pretty common for the replacement literal to be long and
+complex. For instance, it might be an XSS exploit that weighs in at hundreds or
+thousands of characters. To cope with this, there's a variation of the
+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
+
+This will load the replacement text from the file __~/xss-exploit__.
+
+Both the _--replace_ and _--replace-from-file_ flags can be passed multiple
+times.
+
+
+## Interactively
+
+The _R_ shortcut key in mitmproxy lets you add and edit replacement hooks using
+a built-in editor. The context-sensitive help (_h_) has complete usage
+information.
+

doc-src/reverseproxy.html

@@ -1,6 +1,6 @@
 
-- command-line: _-R_ http[s]://hostname[:port]
-- mitmproxy shortcut: _R_
+- command-line: _-P_ http[s]://hostname[:port]
+- mitmproxy shortcut: _P_
 
 In reverse proxy mode, mitmproxy acts as a standard HTTP server and forwards
 all requests to the specified upstream server. Note that the displayed URL for

doc-src/scripts.html

@@ -87,7 +87,7 @@ The main classes you will deal with in writing mitmproxy scripts are:
 
         <td>A dictionary-like object for managing sets of key/value data. There
         is also a variant called CaselessODict that ignores key case for some
-        calls.</td>
+        calls (used mainly for headers).</td>
     </tr>
     <tr>
         <th>libmproxy.flow.Response</th>
@@ -99,10 +99,11 @@ The main classes you will deal with in writing mitmproxy scripts are:
     </tr>
     <tr>
         <th>libmproxy.flow.ScriptContext</th>
-
-
         <td> A handle for interacting with mitmproxy's from within scripts.  </td>
-
+    </tr>
+    <tr>
+        <th>libmproxy.certutils.SSLCert</th>
+        <td>Exposes information SSL certificates.</td>
     </tr>
 </table>
 
@@ -126,5 +127,3 @@ In this case, there are no client connections, and the events are run in the
 following order: __start__, __request__, __response__, __error__, __done__.  If
 the flow doesn't have a __response__ or __error__ associated with it, the
 matching event will be skipped. 
-
-

doc-src/upstreamcerts.html

@@ -1,14 +1,14 @@
 - command-line: _--upstream-cert_ 
 - mitmproxy shortcut: _o_, then _u_
 
-In its normal mode of operation, mitmproxy will use the target domain specified
-in a client's proxy request to generate an interception certificate. When
-__upstream-cert__ mode is activated a different procedure is followed: we first
-connect to the specified remote server to retrieve the server's __Common Name__
-and __Subject Alternative Names__. This feature is especially useful when the
-client specifies an IP address rather than a host name in the proxy request. If
-this is the case, we can only generate a certificate if we can establish the
-__CN__ and __SANs__ from the upstream server.
+Normally, mitmproxy uses the target domain specified in a client's proxy
+request to generate an interception certificate. When __upstream-cert__ mode is
+activated a different procedure is followed: a connection is made to the
+specified remote server to retrieve its __Common Name__ and __Subject
+Alternative Names__. This feature is especially useful when the client
+specifies an IP address rather than a host name in the proxy request. If this
+is the case, we can only generate a certificate if we can establish the __CN__
+and __SANs__ from the upstream server.
 
 Note that __upstream-cert__ mode does not work when the remote server relies on
 [Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication).

libmproxy/cmdline.py

@@ -154,7 +154,7 @@ def common_options(parser):
         help = "Proxy service port."
     )
     parser.add_option(
-        "-R",
+        "-P",
         action="store", dest="reverse_proxy", default=None,
         help="Reverse proxy to upstream server: http[s]://host[:port]"
     )