aboutsummaryrefslogtreecommitdiffstats
path: root/doc-src/features/passthrough.html
blob: 15e3643430a41edc7b20ea5f19b7321b4ea35722 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
There are two main 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.
- **Convenience:** You really don't care about some parts of the traffic and just want them to go away.

If you want to peek into (SSL-protected) non-HTTP connections, check out the [tcp proxy](@!urlTo("tcpproxy.html")!@) feature.
If you want to ignore traffic from mitmproxy's processing because of large response bodies, take a look at the
[response streaming](@!urlTo("responsestreaming.html")!@) feature.

## How it works


<table class="table">
    <tbody>
        <tr>
            <th width="20%">command-line</th> <td>--ignore regex</td>
        </tr>
        <tr>
            <th>mitmproxy shortcut</th> <td><b>I</b></td>
        </tr>
    </tbody>
</table>


mitmproxy allows you to specify a regex which is matched against a <code>host:port</code> 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:

<pre class="terminal">
$ 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
<span style="color: white">127.0.0.1:50588: serverconnect
  -> example.com:443</span>
^C
$ <span style="color: white">mitmproxy --ignore ^example\.com:443$</span>    
</pre>

Here are some other examples for ignore patterns:
<pre>
# Exempt traffic from the iOS App Store (the regex is lax, but usually just works):
--ignore apple.com:443  
# "Correct" version without false-positives:
--ignore ^(.+\.)?apple\.com:443$ 
    
# Ignore example.com, but not its subdomains:
--ignore ^example.com:

# Ignore everything but example.com and mitmproxy.org:
--ignore ^(?!example\.com)(?!mitmproxy\.org)
    
# Transparent mode:
--ignore 17\.178\.96\.59:443
# IP address range:
--ignore 17\.178\.\d+\.\d+:443
</pre>

### See Also

- [TCP Proxy](@!urlTo("tcpproxy.html")!@)
- [Response Streaming](@!urlTo("responsestreaming.html")!@)

[^explicithttp]: This stems from an limitation of explicit HTTP proxying: A single connection can be re-used for multiple target domains - a <code>GET http://example.com/</code> request may be followed by a <code>GET http://evil.com/</code> request on the same connection. If we start to ignore the connection after the first request, we would miss the relevant second one.