From 78a44c5199d81bc46038b5d680638124f613b871 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sun, 7 Sep 2014 00:42:25 +0200 Subject: add docs on proxy modes --- doc-src/modes.html | 210 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 doc-src/modes.html (limited to 'doc-src/modes.html') diff --git a/doc-src/modes.html b/doc-src/modes.html new file mode 100644 index 00000000..77bd1b05 --- /dev/null +++ b/doc-src/modes.html @@ -0,0 +1,210 @@ +Mitmproxy comes with several modes of operation, which allow you to use mitmproxy in a variety of scenarios. +This documents briefly explains each mode and possible setups. +
+Mitmproxy has four modes of operation: + + +

Now, which one should you pick? Use this flow chart: +

+ +

+ +
+

Regular Proxy

+
+ +Mitmproxy's regular mode it the most simple one and the easiest to set up. + +
    +
  1. Start mitmproxy.
    2. +
  2. Configure your client to use mitmproxy. This means that you either adjust the proxy setting of your local browser + or point an external device to your proxy (which should look like + this).
    3. +
  3. Quick Check: You can already visit an unencrypted HTTP site over the proxy.
    4. +
  4. Open the magic domain mitm.it and install the certificate for your device.
    5. +
+ +
+ Heads Up: Unfortunately, some applications prefer to bypass the HTTP proxy settings of the system - + Android applications are a common example. In these cases, you need to use mitmproxy's transparent mode. +
+ +

If you are proxying an external device, your network will probably look like this:

+ +

+

The square brackets signify the source and destination IP addresses. Your client explicitly connects + to mitmproxy and mitmproxy explicitly connects to the target server. +

+ +
+

Transparent Proxy

+
+ +When a transparent proxy is used, traffic is redirected into a proxy at the network layer, without any client +configuration being required. This makes transparent proxying ideal for those situations where you can't change client +behaviour. The basic principle is that mitmproxy sits somewhere on the line from the client to the internet and +transparently intercepts the request. In the graphic below, a machine running mitmproxy has been inserted between +the router and the internet: + + + +

The square brackets signify the source and destination IP addresses. Round brackets mark the next + hop on the Ethernet/data link layer. This distinction is important to make: When the packet arrives + at the mitmproxy machine, it must still be addressed to the target server. In other words: A simple IP redirect on + the router does not work - this would remove the target information, leaving mitmproxy unable to + determine the real destination. +

+ + + +

Common Configurations

+ +The first graphic is a little bit idealistic: Usually, you'll have your local wireless lan network and no +machines between your router and the internet. Fortunately, there are other ways to configure your network: +(a) Configuring the client to use a custom gateway/router/"next hop", (b) Implementing custom routing on the router +or (c) setting up a separate wireless network router which gets proxied. +There are of course other options, but we'll look at these three. In most cases, setting (a) is recommended due to its +ease of use. + +

(a) Custom Gateway

+ +

Looking at your local home network, it's clear what happens if you enter "example.com" into your address bar: After you +press enter, your OS sends a packet to your router, which then sends this to your ISP, which then sends it to some +Tier-1 carrier, which then sends it... I think you get the idea. The important part for us is the first step here: +Your machine is configured to use your router as the next hop. Your router certainly doesn't host example.com, but your +machine knows that your router will forward it upstream. On the technical level, your router probably provides a DHCP +server, which instructs all clients to use his address as the Default Gateway for connections that leave the +current subnet (your local network).

+

+How does this help us? Here comes our trick: By configuring the client to use our machine as its Gateway, all traffic +will be sent to our machine, which then forwards it to the router. This provides us with the scenario we'd like to have, +namely packets on our doorstep that are addressed for someone else: +

+ + + +Given this concept, we can set up mitmproxy: +
    +
  1. Configure your proxy machine for transparent mode.
    You can find instructions + in the Transparent Proxying section of the mitmproxy docs.
    2. +
  2. Configure your client to use your proxy machine's IP as the default gateway. This setting is usually called + Standard Gateway, Router or something along these lines + (iOS screenshot).
    3. +
  3. Quick Check: You can already visit an unencrypted HTTP site over the proxy.
    4. +
  4. Open the magic domain mitm.it and install the certificate for your device.
    5. +
+ +
+ Troubleshooting Transparent Mode +

Wrong transparent mode configurations are a frequent source of + error. If it doesn't work for you, try the following things:

+ + If you encounter any other pitfalls that should be listed here, please let us know! +
+ +

(b) Custom Routing

+ +Custom routing is a fairly advanced setup which we'll only document briefly here. +First and foremost, it usually requires root on your router. The basic idea is to teach your router a custom routing +table that says "for requests from ip X, the proxy machine is the next gateway". + + + + +For this setup, we expect you to have a basic understanding of networking in general. In short, you should get started +with these routing commands. The Troubleshooting part directly above this +section might be helpful for you as well. + +

(c) Separate Network

+ +Setting up a separate network using a cheap router might be a viable option, too. Such a configuration mostly resembles +the idealistic graphic from the beginning (Variant 1). Take a look at the +Transparently proxify virtual machines tutorial to see how +such a network could be implemented. The troubleshooting section for custom gateways may be helpful for you, too. + + +
+

Reverse Proxy

+
+ +Mitmproxy is usually used with a client that uses the proxy to access the Internet. Using reverse proxy mode, you can +use mitmproxy to represent a server: + + + + +There are various use-cases: + + +

+Please note that cloning Google by using mitmproxy -R http://google.com/ does not really work +(as in this screenshot). +This may work for the first request, but the HTML remains unchanged: As soon as the user clicks on an non-relative URL +(or downloads a non-relative image resource), they speak with Google directly again. +

+

+ On another note, mitmproxy either supports an HTTP or an HTTPS upstream server, not both at the same time. You can + simply work around this by spawning a second mitmproxy instance. Each instance listens to one port and talks to one + port. +

+ +
+

Upstream Proxy

+
+ +

+If you want to add mitmproxy in front of a different proxy appliance, you can use mitmproxy's upstream mode. +In upstream mode, all requests are unconditionally transferred to an upstream proxy or your choice. +

+ + + + +

+mitmproxy supports both explicit HTTP and explicit HTTPS in upstream proxy mode. You could in theory chain multiple +mitmproxy instances in a row, but that doesn't make any sense in practice (i.e. outside of our tests). +

\ No newline at end of file -- cgit v1.2.3