From 6dbe431c5e680d1c7f693a4c7bb7f3f65314c5c6 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Mon, 8 Sep 2014 13:41:25 +0200 Subject: document --ignore, fix #350 --- doc-src/_nav.html | 9 +++-- doc-src/features/index.py | 13 ++++--- doc-src/features/passthrough.html | 77 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 9 deletions(-) create mode 100644 doc-src/features/passthrough.html (limited to 'doc-src') diff --git a/doc-src/_nav.html b/doc-src/_nav.html index 02ea68e4..822e9fa6 100644 --- a/doc-src/_nav.html +++ b/doc-src/_nav.html @@ -10,18 +10,21 @@
  • Features
    • $!nav("anticache.html", this, state)!$ - $!nav("clientreplay.html", this, state)!$ + $!nav("filters.html", this, state)!$ - $!nav("upstreamproxy.html", this, state)!$ - $!nav("proxyauth.html", this, state)!$ $!nav("replacements.html", this, state)!$ + $!nav("clientreplay.html", this, state)!$ $!nav("serverreplay.html", this, state)!$ $!nav("setheaders.html", this, state)!$ + $!nav("passthrough.html", this, state)!$ $!nav("sticky.html", this, state)!$ $!nav("reverseproxy.html", this, state)!$ + $!nav("upstreamproxy.html", this, state)!$ $!nav("upstreamcerts.html", this, state)!$ + $!nav("proxyauth.html", this, state)!$ $!nav("responsestreaming.html", this, state)!$ +
  • Installing Certificates
    • $!nav("ssl.html", this, state)!$ $!nav("certinstall/webapp.html", this, state)!$ diff --git a/doc-src/features/index.py b/doc-src/features/index.py index b4d441d1..477bb8af 100644 --- a/doc-src/features/index.py +++ b/doc-src/features/index.py @@ -4,13 +4,14 @@ pages = [ Page("anticache.html", "Anticache"), Page("clientreplay.html", "Client-side replay"), Page("filters.html", "Filter expressions"), - Page("upstreamproxy.html", "Upstream proxy mode"), - Page("setheaders.html", "Set Headers"), - Page("serverreplay.html", "Server-side replay"), - Page("sticky.html", "Sticky cookies and auth"), + Page("passthrough.html", "Ignore Domains"), Page("proxyauth.html", "Proxy Authentication"), Page("replacements.html", "Replacements"), + Page("responsestreaming.html", "Response Streaming"), Page("reverseproxy.html", "Reverse proxy mode"), + Page("setheaders.html", "Set Headers"), + Page("serverreplay.html", "Server-side replay"), + Page("sticky.html", "Sticky cookies and auth"), Page("upstreamcerts.html", "Upstream Certs"), - Page("responsestreaming.html", "Response Streaming"), -] + Page("upstreamproxy.html", "Upstream proxy mode"), +] \ No newline at end of file diff --git a/doc-src/features/passthrough.html b/doc-src/features/passthrough.html new file mode 100644 index 00000000..039d6b58 --- /dev/null +++ b/doc-src/features/passthrough.html @@ -0,0 +1,77 @@ +There are a couple of reasons why you may want to exempt some traffic from mitmproxy's interception mechanism: + +- **Certificate pinning:** Some traffic is is protected using + [certificate pinning](https://security.stackexchange.com/questions/29988/what-is-certificate-pinning) and mitmproxy's + interception leads to errors. For example, Windows Update or the Apple App Store fail to work if mitmproxy is active. +- **Non-HTTP traffic:** WebSockets or other non-http protocols are not supported by mitmproxy yet. You can exempt the + domain from processing, which would otherwise fail. +- **Convenience:** You really don't care about some parts of the traffic and just want them to go away. + +If you want to ignore traffic from mitmproxy's processing because of large response bodies, check out the +[response streaming](@!urlTo("responsestreaming.html")!@) feature. + +## How it works + + + + + + + + + + + +
    command-line --ignore regex
    mitmproxy shortcut I
    + + +mitmproxy allows you to specify a regex which is matched against a host:port string (e.g. "example.com:443") +to determine hosts that should be excluded. + +There are two important quirks to consider: + +- **In transparent mode, the ignore pattern is matched against the IP.** While we usually infer the hostname from the + Host header if the --host argument is passed to mitmproxy, we do not have access to this information before the SSL + handshake. +- In regular mode, explicit HTTP requests are never ignored.[^explicithttp] The ignore pattern is applied on CONNECT + requests, which initiate HTTPS or clear-text WebSocket connections. + + +### Tutorial + +If you just want to ignore one specific domain, there's usually a bulletproof method to do so: + +1. Run mitmproxy or mitmdump in verbose mode (-v) and observe the host:port information in the serverconnect +messages. mitmproxy will filter on these. +2. Take the host:port string, surround it with ^ and $, escape all dots (. becomes \\.) +and use this as your ignore pattern: + +
    +$ mitmdump -v
+127.0.0.1:50588: clientconnect
+127.0.0.1:50588: request
+  -> CONNECT example.com:443 HTTP/1.1
+127.0.0.1:50588: Set new server address: example.com:443
+127.0.0.1:50588: serverconnect
+  -> example.com:443
+^C
+$ mitmproxy --ignore ^example\.com:443$    
+
    + +Here are some other examples for ignore patterns: +
    +# Exempt traffic from the iOS App Store (usually just works):
+--ignore apple.com:443  
+# "Correct" version without false-positives:
+--ignore ^(.+\.)?apple\.com:443$ 
+    
+# Ignore example.com on all ports, but no subdomains:
+--ignore ^example.com:
+    
+# Transparent mode:
+--ignore 17\.178\.96\.59:443
+# IP address range:
+--ignore 17\.178\.\d+\.\d+:443
+
    + +[^explicithttp]: This stems from an limitation of explicit HTTP proxying: A single connection can be re-used for multiple target domains - a GET http://example.com/ request may be followed by a GET http://evil.com/ request on the same connection. If we start to ignore the connection after the first request, we would miss the relevant second one. \ No newline at end of file -- cgit v1.2.3