From 4da8054e215ec8594ac17075f116f9d26cee7bfa Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Wed, 4 Apr 2012 14:17:26 +1200 Subject: [PATCH] Docs: replacements, upstream certs. Also, move reverse proxy command-line flag to -P. --- doc-src/replacements.html | 59 ++++++++++++++++++++++++++++++++++++++ doc-src/reverseproxy.html | 4 +-- doc-src/scripts.html | 11 ++++--- doc-src/upstreamcerts.html | 16 +++++------ libmproxy/cmdline.py | 2 +- 5 files changed, 75 insertions(+), 17 deletions(-) diff --git a/doc-src/replacements.html b/doc-src/replacements.html index e69de29bb..27a4fd4b1 100644 --- a/doc-src/replacements.html +++ b/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. + diff --git a/doc-src/reverseproxy.html b/doc-src/reverseproxy.html index 125be19ab..4160b5c62 100644 --- a/doc-src/reverseproxy.html +++ b/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 diff --git a/doc-src/scripts.html b/doc-src/scripts.html index 3fa79a6c6..be8e54810 100644 --- a/doc-src/scripts.html +++ b/doc-src/scripts.html @@ -87,7 +87,7 @@ The main classes you will deal with in writing mitmproxy scripts are: 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. + calls (used mainly for headers). libmproxy.flow.Response @@ -99,10 +99,11 @@ The main classes you will deal with in writing mitmproxy scripts are: libmproxy.flow.ScriptContext - - A handle for interacting with mitmproxy's from within scripts. - + + + libmproxy.certutils.SSLCert + Exposes information SSL certificates. @@ -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. - - diff --git a/doc-src/upstreamcerts.html b/doc-src/upstreamcerts.html index 804286d9b..32a13a9a8 100644 --- a/doc-src/upstreamcerts.html +++ b/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). diff --git a/libmproxy/cmdline.py b/libmproxy/cmdline.py index 483adfc06..dd1f328bb 100644 --- a/libmproxy/cmdline.py +++ b/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]" )