From 8e6fabd69a124cc5b5ae763b58587ee6ee6ab3da Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Wed, 2 Jan 2013 21:57:39 +1300 Subject: [PATCH] Docs - features. --- doc-src/anticache.html | 14 +++++++++--- doc-src/clientreplay.html | 15 ++++++++++--- doc-src/proxyauth.html | 25 +++++++++++++++++++++- doc-src/replacements.html | 19 +++++++++++++--- doc-src/reverseproxy.html | 15 ++++++++++--- doc-src/sticky.html | 44 +++++++++++++++++++++++++++++++------- doc-src/upstreamcerts.html | 32 ++++++++++++++++----------- 7 files changed, 130 insertions(+), 34 deletions(-) diff --git a/doc-src/anticache.html b/doc-src/anticache.html index d97e9f5f9..f42903e8a 100644 --- a/doc-src/anticache.html +++ b/doc-src/anticache.html @@ -1,10 +1,18 @@ -- command-line: _--anticache_ -- mitmproxy shortcut: _o_, then _a_ - When the __anticache__ option is passed to mitmproxy, it removes headers (__if-none-match__ and __if-modified-since__) that might elicit a 304-not-modified response from the server. This is useful when you want to make sure you capture an HTTP exchange in its totality. It's also often used during [client replay](@!urlTo("clientreplay.html")!@), when you want to make sure the server responds with complete data. + + + + + + + + + + +
command-line --anticache
mitmproxy shortcut o then a
diff --git a/doc-src/clientreplay.html b/doc-src/clientreplay.html index c94f50348..6638d0780 100644 --- a/doc-src/clientreplay.html +++ b/doc-src/clientreplay.html @@ -1,7 +1,4 @@ -- command-line: _-c path_ -- mitmproxy shortcut: _c_ - Client-side replay does what it says on the tin: you provide a previously saved HTTP conversation, and mitmproxy replays the client requests one by one. Note that mitmproxy serializes the requests, waiting for a response from the server @@ -11,3 +8,15 @@ conversation, where requests may have been made concurrently. You may want to use client-side replay in conjunction with the [anticache](@!urlTo("anticache.html")!@) option, to make sure the server responds with complete data. + + + + + + + + + + + +
command-line -c path
mitmproxy shortcut c
diff --git a/doc-src/proxyauth.html b/doc-src/proxyauth.html index 224b9e2d8..0618ee681 100644 --- a/doc-src/proxyauth.html +++ b/doc-src/proxyauth.html @@ -1,2 +1,25 @@ -Proxy auth. + +Asks the user for authentication before they are permitted to use the proxy. +Authentication headers are stripped from the flows, so they are not passed to +upstream servers. For now, only HTTP Basic authentication is supported. + + + + + + + + +
command-line +
    +
  • --nonanonymous
    • + +
  • --singleuser USER
    • + +
  • --htpasswd PATH
    • +
+
+ + + diff --git a/doc-src/replacements.html b/doc-src/replacements.html index 986e773a7..c10fe2c36 100644 --- a/doc-src/replacements.html +++ b/doc-src/replacements.html @@ -1,6 +1,3 @@ -- 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 @@ -59,3 +56,19 @@ 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. + + + + + + + + + + +
command-line +
    +
  • --replace
    • +
  • --replace-from-file
    • +
+
mitmproxy shortcut R
diff --git a/doc-src/reverseproxy.html b/doc-src/reverseproxy.html index 4160b5c62..524df0838 100644 --- a/doc-src/reverseproxy.html +++ b/doc-src/reverseproxy.html @@ -1,8 +1,17 @@ -- 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 flows in this mode will use the value of the __Host__ header field from the request, not the reverse proxy server. + + + + + + + + + + + +
command-line -P http[s]://hostname[:port]
mitmproxy shortcut P
diff --git a/doc-src/sticky.html b/doc-src/sticky.html index 6208f658b..1b79f9224 100644 --- a/doc-src/sticky.html +++ b/doc-src/sticky.html @@ -1,10 +1,6 @@ ## Sticky cookies -- command-line: _-t_ (sticky cookies on all requests) -- command-line: _-T filt_ (sticky cookies on requests matching filt) -- mitmproxy shortcut: _t_ - When the sticky cookie option is set, __mitmproxy__ will add the cookie most recently set by the server to any cookie-less request. Consider a service that sets a cookie to track the session after authentication. Using sticky cookies, @@ -20,15 +16,47 @@ replay](@!urlTo("clientreplay.html")!@) - you can record the authentication process once, and simply replay it on startup every time you need to interact with the secured resources. + + + + + + + + + + +
command-line +
    +
  • -t (sticky cookies on all requests)
    • +
  • -T FILTER (sticky cookies on requests matching filter
    • +
+
mitmproxy shortcut t
+ ## Sticky auth -- command-line: _-u_ (sticky auth on all requests) -- command-line: _-U filt_ (sticky auth on requests matching filt) -- mitmproxy shortcut: _u_ - The sticky auth option is analogous to the sticky cookie option, in that HTTP __Authorization__ headers are simply replayed to the server once they have been seen. This is enough to allow you to access a server resource using HTTP Basic authentication through the proxy. Note that __mitmproxy__ doesn't (yet) support replay of HTTP Digest authentication. + + + + + + + + + + + +
command-line +
    +
  • -u (sticky auth on all requests)
    • +
  • -U FILTER (sticky auth on requests matching filter
    • +
+
mitmproxy shortcut u
+ + diff --git a/doc-src/upstreamcerts.html b/doc-src/upstreamcerts.html index 32a13a9a8..8de75ee34 100644 --- a/doc-src/upstreamcerts.html +++ b/doc-src/upstreamcerts.html @@ -1,15 +1,21 @@ -- command-line: _--upstream-cert_ -- mitmproxy shortcut: _o_, then _u_ +When mitmproxy receives a connection destined for an SSL-protected service, it +freezes the connection before reading its request data, and makes a connection +to the upstream server to "sniff" the contents of its SSL certificate. The +information gained - the __Common Name__ and __Subject Alternative Names__ - is +then used to generate the interception certificate, which is sent to the client +so the connection can continue. -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. +This rather intricate little dance lets us seamlessly generate correct +certificates even if the client has specifed only an IP address rather than the +hostname. It also means that we don't need to sniff additional data to generate +certs in transparent mode. -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). -Luckily, SNI is still not very widely used. +Upstream cert sniffing is on by default, and can optionally be turned off. + + + + + + + +
command-line --no-upstream-cert