From e1148584380058f264b7aa7e9493115e4e8f2bbe Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sat, 18 Oct 2014 18:29:35 +0200 Subject: add generic tcp proxying, fix #374 --- doc-src/_nav.html | 1 + doc-src/features/index.py | 1 + doc-src/features/passthrough.html | 12 ++++++++---- doc-src/features/responsestreaming.html | 6 +++++- doc-src/features/tcpproxy.html | 30 ++++++++++++++++++++++++++++++ 5 files changed, 45 insertions(+), 5 deletions(-) create mode 100644 doc-src/features/tcpproxy.html (limited to 'doc-src') diff --git a/doc-src/_nav.html b/doc-src/_nav.html index 822e9fa6..8bd03db2 100644 --- a/doc-src/_nav.html +++ b/doc-src/_nav.html @@ -17,6 +17,7 @@ $!nav("serverreplay.html", this, state)!$ $!nav("setheaders.html", this, state)!$ $!nav("passthrough.html", this, state)!$ + $!nav("tcpproxy.html", this, state)!$ $!nav("sticky.html", this, state)!$ $!nav("reverseproxy.html", this, state)!$ $!nav("upstreamproxy.html", this, state)!$ diff --git a/doc-src/features/index.py b/doc-src/features/index.py index 477bb8af..40a2669c 100644 --- a/doc-src/features/index.py +++ b/doc-src/features/index.py @@ -12,6 +12,7 @@ pages = [ Page("setheaders.html", "Set Headers"), Page("serverreplay.html", "Server-side replay"), Page("sticky.html", "Sticky cookies and auth"), + Page("tcpproxy.html", "TCP Proxy"), Page("upstreamcerts.html", "Upstream Certs"), 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 index 039d6b58..7c830639 100644 --- a/doc-src/features/passthrough.html +++ b/doc-src/features/passthrough.html @@ -1,13 +1,12 @@ -There are a couple of reasons why you may want to exempt some traffic from mitmproxy's interception mechanism: +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. -- **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 +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 @@ -74,4 +73,9 @@ Here are some other examples for ignore patterns: --ignore 17\.178\.\d+\.\d+:443 +### 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 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 diff --git a/doc-src/features/responsestreaming.html b/doc-src/features/responsestreaming.html index d20af65c..47fafef7 100644 --- a/doc-src/features/responsestreaming.html +++ b/doc-src/features/responsestreaming.html @@ -47,4 +47,8 @@ When response streaming is enabled, portions of the code which would have otherw on the response body will see an empty response body instead (libmproxy.protocol.http.CONTENT_MISSING). Any modifications will be ignored. Streamed responses are usually sent in chunks of 4096 bytes. If the response is sent with a Transfer-Encoding: - chunked header, the response will be streamed one chunk at a time. \ No newline at end of file + chunked header, the response will be streamed one chunk at a time. + +### See Also + +- [Ignore Domains](@!urlTo("passthrough.html")!@) diff --git a/doc-src/features/tcpproxy.html b/doc-src/features/tcpproxy.html new file mode 100644 index 00000000..819cf297 --- /dev/null +++ b/doc-src/features/tcpproxy.html @@ -0,0 +1,30 @@ +WebSockets or other non-HTTP protocols are not supported by mitmproxy yet. However, you can exempt hostnames from +processing, so that mitmproxy acts as a generic TCP forwarder. This feature is closely related to the +[ignore domains](@!urlTo("passthrough.html")!@) functionality, but differs in two important aspects: + +- The raw TCP messages are printed to the event log. +- SSL connections will be intercepted. + +Please note that message interception or modification are not possible yet. +If you are not interested in the raw TCP messages, you should use the ignore domains feature. + +## How it works + + + + + + + + + + + +
command-line --tcp HOST
mitmproxy shortcut T
+ +For a detailed description on the structure of the hostname pattern, please refer to the [Ignore Domains](@!urlTo("passthrough.html")!@) feature. + +### See Also + +- [Ignore Domains](@!urlTo("passthrough.html")!@) +- [Response Streaming](@!urlTo("responsestreaming.html")!@) -- cgit v1.2.3 From 3848a27d31a9b04c8114d0260c4b9a615d83c8cd Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Wed, 22 Oct 2014 13:59:47 +0200 Subject: fix #378 --- doc-src/ssl.html | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'doc-src') diff --git a/doc-src/ssl.html b/doc-src/ssl.html index 91225d79..16aed1dc 100644 --- a/doc-src/ssl.html +++ b/doc-src/ssl.html @@ -41,10 +41,26 @@ The files created by mitmproxy in the .mitmproxy directory are as follows: Using a custom certificate -------------------------- -You can use your own certificate by passing the __--cert__ option to mitmproxy. +You can use your own certificate by passing the --cert option to mitmproxy. mitmproxy then uses the provided +certificate for interception of the specified domains instead of generating a cert signed by its own CA. -The certificate file is expected to be in the PEM format. You can generate -a certificate in this format using these instructions: +The certificate file is expected to be in the PEM format. +You can include intermediary certificates right below your leaf certificate, so that you PEM file roughly looks like +this: + +
+-----BEGIN PRIVATE KEY-----
+<private key>
+-----END PRIVATE KEY-----
+-----BEGIN CERTIFICATE-----
+<cert>
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+<intermediary cert (optional)>
+-----END CERTIFICATE-----
+
+ +For example, you can generate a certificate in this format using these instructions: 
 > openssl genrsa -out cert.key 8192
-- 
cgit v1.2.3


From 05590cf6c272571aa812ace321aa30573f2e125c Mon Sep 17 00:00:00 2001
From: Aldo Cortesi 
Date: Thu, 23 Oct 2014 09:44:47 +1300
Subject: Documentation re-org

- No longer using README.md in the rendered documentation.
- Rendered doc instrutions are now for the released version of
mitmproxy, with dev install instructions in the README.md
---
 doc-src/index.html   | 25 ++++++++++++++++++++++++-
 doc-src/index.py     | 13 ++++++++-----
 doc-src/install.html | 24 ------------------------
 3 files changed, 32 insertions(+), 30 deletions(-)

(limited to 'doc-src')

diff --git a/doc-src/index.html b/doc-src/index.html
index 79687ec6..23da7223 100644
--- a/doc-src/index.html
+++ b/doc-src/index.html
@@ -1,4 +1,27 @@
 
-@!index_contents!@
+__mitmproxy__ is an interactive, SSL-capable man-in-the-middle proxy for HTTP
+with a console interface.
 
+__mitmdump__ is the command-line version of mitmproxy. Think tcpdump for HTTP.
+
+__libmproxy__ is the library that mitmproxy and mitmdump are built on.
+
+Documentation, tutorials and distribution packages can be found on the
+mitmproxy.org website:
+
+[mitmproxy.org](http://mitmproxy.org).
+
+
+Features
+--------
+
+- Intercept HTTP requests and responses and modify them on the fly.
+- Save complete HTTP conversations for later replay and analysis.
+- Replay the client-side of an HTTP conversations.
+- Replay HTTP responses of a previously recorded server.
+- Reverse proxy mode to forward traffic to a specified server.
+- Transparent proxy mode on OSX and Linux.
+- Make scripted changes to HTTP traffic using Python.
+- SSL certificates for interception are generated on the fly.
+- And much, much more.
 
diff --git a/doc-src/index.py b/doc-src/index.py
index b7ab9995..e6064e3a 100644
--- a/doc-src/index.py
+++ b/doc-src/index.py
@@ -1,6 +1,8 @@
-import os, sys, datetime
+import os
+import sys
+import datetime
 import countershape
-from countershape import Page, Directory, PythonModule, markup, model
+from countershape import Page, Directory, markup, model
 import countershape.template
 sys.path.insert(0, "..")
 from libmproxy import filt, version
@@ -23,18 +25,18 @@ ns.docMaintainer = "Aldo Cortesi"
 ns.docMaintainerEmail = "aldo@corte.si"
 ns.copyright = u"\u00a9 mitmproxy project, %s" % datetime.date.today().year
 
+
 def mpath(p):
     p = os.path.join(MITMPROXY_SRC, p)
     return os.path.expanduser(p)
 
-with open(mpath("README.mkd")) as f:
-        readme = f.read()
-        ns.index_contents = readme.split("\n", 1)[1] #remove first line (contains build status)
 
 def example(s):
     d = file(mpath(s)).read().rstrip()
     extemp = """
%s
(%s)
"""
     return extemp%(countershape.template.Syntax("py")(d), s)
+
+
 ns.example = example
 
 
@@ -73,6 +75,7 @@ def nav(page, current, state):
 ns.nav = nav
 ns.navbar = countershape.template.File(None, "_nav.html")
 
+
 pages = [
     Page("index.html", "Introduction"),
     Page("install.html", "Installation"),
diff --git a/doc-src/install.html b/doc-src/install.html
index 5d412459..5f1e54fd 100644
--- a/doc-src/install.html
+++ b/doc-src/install.html
@@ -4,30 +4,11 @@ release or from source - is to use [pip](http://www.pip-installer.org/). If you
 don't already have pip on your system, you can find installation instructions
 [here](http://www.pip-installer.org/en/latest/installing.html).
 
-
-## Installing the latest release
-
-A single command will download and install the latest release of mitmproxy,
-along with all its dependencies:
-
 
 pip install mitmproxy
 

 
 
-## Installing from source
-
-When installing from source, the easiest method is still to use pip. In this
-case run:
-    
-
-pip install /path/to/source
-

-
-Note that if you're installing current git master, you will also have to
-install the current git master of [netlib](http://github.com/mitmproxy/netlib) by
-hand.
-
 ## OSX
 
 - If you're running a Python interpreter installed with homebrew (or similar),
@@ -64,8 +45,3 @@ from source:
 - libxslt1-dev
 
 
-
-
-
-
-
-- 
cgit v1.2.3


From 4da90724a0368ddf112644d29545a6ecc92a2861 Mon Sep 17 00:00:00 2001
From: Aldo Cortesi 
Date: Thu, 23 Oct 2014 12:56:31 +1300
Subject: First redraft of modes documentation

---
 doc-src/modes.html | 298 ++++++++++++++++++++++++++++-------------------------
 1 file changed, 155 insertions(+), 143 deletions(-)

(limited to 'doc-src')

diff --git a/doc-src/modes.html b/doc-src/modes.html
index 77bd1b05..b78fe3c0 100644
--- a/doc-src/modes.html
+++ b/doc-src/modes.html
@@ -1,210 +1,222 @@
-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:
-
    
-    
  • Regular Mode (this is what you get by default)
    • 
-    
  • Transparent Mode
    • 
-    
  • Reverse Proxy Mode
    • 
-    
  • Upstream Proxy Mode
    • 
-

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

-
-


+
+Mitmproxy has four modes of operation that allow you to use mitmproxy in a
+variety of scenarios:
+
+- **Regular** (the default)
+- **Transparent**
+- **Reverse Proxy**
+- **Upstream Proxy**
+
+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.
+Mitmproxy's regular mode is the simplest 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. 
-

+1. Start mitmproxy.
+2. Configure your client to use mitmproxy. For instance on IOS, the settings might look like this.
+3. Quick Check: You should already be able to visit an unencrypted HTTP site
+through the proxy.
+4. Open the magic domain mitm.it and install the certificate for your device.
 
 

-    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.
+Heads Up: Unfortunately, some applications bypass the
+system HTTP proxy settings - 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:

+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.
-

+
+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:
+In transparent mode, traffic is directed into a proxy at the network layer,
+without any client configuration required. This makes transparent proxying
+ideal for situations where you can't change client behaviour. 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.
-

+    
+
+
+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: when the packet arrives at the mitmproxy machine, it must still
+be addressed to the target server. This means that Network Address Translation
+should not be applied before the traffic reaches mitmproxy, since 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.
+There are many ways to configure your network for transparent proxying. We'll
+look at three common scenarios:
+
+1. Configuring the client to use a custom gateway/router/"next hop"
+2. Implementing custom routing on the router
+
+In most cases, the first option 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:
-

+One simple way to get traffic to the mitmproxy machine with the destination IP
+intact, is to simply configure the client with the mitmproxy box as the
+default gateway.
+
 
     
 
-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. 
-

+In this scenario, we would:
+
+- Configure the proxy machine for transparent mode. You can find instructions
+in the Transparent Proxying section of the mitmproxy docs.
+
+- Configure the client to use the proxy machine's IP as the default gateway.
+Here is what this would
+look like on IOS.
+
+- Quick Check: At this point, you should already be able to visit an
+unencrypted HTTP site over the proxy.
+
+- Open the magic domain mitm.it and install the certificate
+for your device.
+
+Setting the custom gateway on clients can be automated by serving the settings
+out to clients over DHCP. This lets set up an interception network where all
+clients are proxied automatically, which can save time and effort. 
+
 
 

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

+
     
    
-        
  • Open mitmproxy's event log (press `e`) - can you spot clientconnect messages?
-        If not, the packets are not arriving at the proxy. A common source is the occurence of ICMP redirects,
-            which means that your machine is telling the client that there's a faster way to the internet by contacting
-            your router directly (see the Transparent Proxying section on how to disable them). If in doubt,
-            Wireshark may help you to see whether something arrives at your machine
-            or not.
+        
  • 
+            Open mitmproxy's event log (press `e`) - do you see clientconnect
+            messages? If not, the packets are not arriving at the proxy. One common
+            cause is the occurrence of ICMP redirects, which means that your
+            machine is telling the client that there's a faster way to the
+            internet by contacting your router directly (see the
+            Transparent Proxying section on how to disable them). If in
+            doubt, Wireshark may help you
+            to see whether something arrives at your machine or not.
         
    • 
         
  • 
-            Have you explicitly configured an HTTP proxy on your device? You do not need mitmproxy's transparent mode
-            then, just start mitmproxy normally. Explicitly setting a proxy and transparent mode contradict each other,
-            settle for one. Do not explicitly redirect traffic to mitmproxy anywhere except for the Gateway setting.
+            Make sure you have not explicitly configured an HTTP proxy on the
+            client. This is not needed in transparent mode.
         
    • 
         
  • 
             Re-check the instructions in the Transparent Proxying section. Anything you missed?
         
    • 
     

+
     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".
+In some cases, you may need more fine-grained control of which traffic reaches
+the mitmproxy instance, and which doesn't. You may, for instance, choose only
+to divert traffic to some hosts into the transparent proxy. There are a huge
+number of ways to accomplish this, and much will depend on the router or
+packet filter you're using. In most cases, the configuration will look like
+this:
 
 
-    
-
-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:
+Mitmproxy is usually used with a client that uses the proxy to access the
+Internet. Using reverse proxy mode, you can use mitmproxy to act like a normal
+HTTP server:
 
 
-    
+    
+
 
 There are various use-cases:
-
    
-
  • 
-    Say you have an internal API running at http://example.local/. You could now setup mitmproxy in
-    reverse proxy mode at http://debug.example.local/ and dynamically point clients to this new API endpoint,
-    which provides clients with the same data and you with debug information. Similarly, you could move your real server
-    to a different ip/port and setup mitmproxy at the original place to debug all sessions.
-
    • 
-
  • 
-    Say you're a web developer working on example.com (with a development version running on localhost:8000).
-    You can modify your hosts file so that example.com points to 127.0.0.1 and then run mitmproxy in reverse proxy
-    mode on port 80. You can test your app on the example.com domain and get all requests recorded in mitmproxy.
-
    • 
-
  • 
-    Say you have some toy project that should get SSL support. Simply setup mitmproxy with SSL termination and you're
-    done (mitmdump -p 443 -R https2http://localhost:80/). There are better tools for this specific task (we don't
-    have C performance obviously), but it's definitely a nice and very quick way to setup an SSL-speaking server.
-
    • 
-
  • 
-    Want to add a non-SSL-capable compression proxy in front of your server? You could even spawn a mitmproxy instance
-    that terminates SSL (https2http://...), point it to the compression proxy and let the compression proxy point
-    to a SSL-initiating mitmproxy (http2https://...), which then points to the real server. As you see, it's a fairly
-    flexible thing.
-
    • 
-

-
-

-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.
-

+
+- Say you have an internal API running at http://example.local/. You could now
+set up mitmproxy in reverse proxy mode at http://debug.example.local/ and
+dynamically point clients to this new API endpoint, which provides clients
+with the same data and you with debug information. Similarly, you could move
+your real server to a different IP/port and set up mitmproxy at the original
+place to debug all sessions.
+
+- Say you're a web developer working on example.com (with a development
+version running on localhost:8000). You can modify your hosts file so that
+example.com points to 127.0.0.1 and then run mitmproxy in reverse proxy mode
+on port 80. You can test your app on the example.com domain and get all
+requests recorded in mitmproxy.
+
+- Say you have some toy project that should get SSL support. Simply set up
+mitmproxy with SSL termination and you're done (mitmdump -p 443 -R
+https2http://localhost:80/). There are better tools for this specific
+task, but mitmproxy is very quick and simple way to set up an SSL-speaking
+server.
+
+- Want to add a non-SSL-capable compression proxy in front of your server? You
+could even spawn a mitmproxy instance that terminates SSL (https2http://...),
+point it to the compression proxy and let the compression proxy point to a
+SSL-initiating mitmproxy (http2https://...), which then points to the real
+server. As you see, it's a fairly flexible thing.
+
+Note that mitmproxy supports either an HTTP or an HTTPS upstream server, not
+both at the same time. You can work around this by spawning a second mitmproxy
+instance.
+
+

+    Caveat: Interactive Use
+
+
+One caveat is that reverse proxy mode is often not sufficient for interactive
+browsing. Consider trying to clone Google by using:
+
+mitmproxy -R http://google.com/
+
+This works for the initial request, but the HTML served to the client remains
+unchanged. As soon as the user clicks on an non-relative URL (or downloads a
+non-relative image resource), traffic no longer passes through mitmproxy, and
+the client connects to Google directly again.
+
+

+
+
 
 

     
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.
-

+If you want to chain proxies by adding 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
+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). 
-- 
cgit v1.2.3


From 5aace7eed8899756799679f7667739dfb58b4dbc Mon Sep 17 00:00:00 2001
From: Aldo Cortesi 
Date: Thu, 23 Oct 2014 15:05:01 +1300
Subject: Keep sidebar ordering alphabetical, add SOCKS documentation

---
 doc-src/_nav.html                |  9 +++++----
 doc-src/features/index.py        |  1 +
 doc-src/features/socksproxy.html | 10 ++++++++++
 3 files changed, 16 insertions(+), 4 deletions(-)
 create mode 100644 doc-src/features/socksproxy.html

(limited to 'doc-src')

diff --git a/doc-src/_nav.html b/doc-src/_nav.html
index 8bd03db2..0ae0fa67 100644
--- a/doc-src/_nav.html
+++ b/doc-src/_nav.html
@@ -17,13 +17,14 @@
         $!nav("serverreplay.html", this, state)!$
         $!nav("setheaders.html", this, state)!$
         $!nav("passthrough.html", this, state)!$
-        $!nav("tcpproxy.html", this, state)!$
-        $!nav("sticky.html", this, state)!$
+        $!nav("proxyauth.html", this, state)!$
         $!nav("reverseproxy.html", this, state)!$
+        $!nav("responsestreaming.html", this, state)!$
+        $!nav("socksproxy.html", this, state)!$
+        $!nav("sticky.html", this, state)!$
+        $!nav("tcpproxy.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
    • 
diff --git a/doc-src/features/index.py b/doc-src/features/index.py
index 40a2669c..693b4439 100644
--- a/doc-src/features/index.py
+++ b/doc-src/features/index.py
@@ -9,6 +9,7 @@ pages = [
     Page("replacements.html", "Replacements"),
     Page("responsestreaming.html", "Response Streaming"),
     Page("reverseproxy.html", "Reverse proxy mode"),
+    Page("socksproxy.html", "SOCKS Mode"),
     Page("setheaders.html", "Set Headers"),
     Page("serverreplay.html", "Server-side replay"),
     Page("sticky.html", "Sticky cookies and auth"),
diff --git a/doc-src/features/socksproxy.html b/doc-src/features/socksproxy.html
new file mode 100644
index 00000000..f436cbf5
--- /dev/null
+++ b/doc-src/features/socksproxy.html
@@ -0,0 +1,10 @@
+
+In this mode, mitmproxy acts as a SOCKS5 proxy server.
+
+
+    
+        
+            
+        
+    
+
    command-line --socks
    
-- 
cgit v1.2.3


From 32127f80e2bd3ee5b33610300d11abafc9c6e3ae Mon Sep 17 00:00:00 2001
From: Aldo Cortesi 
Date: Thu, 23 Oct 2014 15:43:06 +1300
Subject: More refactoring of installation docs

- Make it clear that README.md only has the hacking installation
instructions
- Beef up install.html
---
 doc-src/install.html | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

(limited to 'doc-src')

diff --git a/doc-src/install.html b/doc-src/install.html
index 5f1e54fd..8a76e3ae 100644
--- a/doc-src/install.html
+++ b/doc-src/install.html
@@ -1,4 +1,8 @@
 
+
+
+## Installing from source
+
 The preferred way to install mitmproxy - whether you're installing the latest
 release or from source - is to use [pip](http://www.pip-installer.org/). If you
 don't already have pip on your system, you can find installation instructions
@@ -8,14 +12,24 @@ don't already have pip on your system, you can find installation instructions
 pip install mitmproxy
    +If you also want to install the optional packages AMF, protobuf and CSS +content views, do this: + +
    +pip install "mitmproxy[contentviews]"
+
    + ## OSX +The easiest way to get up and running on OSX is to download the pre-built +binary packages from [mitmproxy.org](http://mitmproxy.org). If you still want +to install using pip, there are a few things to keep in mind: + - If you're running a Python interpreter installed with homebrew (or similar), you may have to install some dependencies by hand. - Make sure that XCode is installed from the App Store, and that the command-line tools have been downloaded (XCode/Preferences/Downloads). -- Now use __pip__ to do the installation, as above. There are a few bits of customization you might want to do to make mitmproxy comfortable to use on OSX. The default color scheme is optimized for a dark -- cgit v1.2.3 From 6aa05df944add1fe7b681ae6e7d6336f2ff3ae55 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Thu, 23 Oct 2014 15:50:43 +1300 Subject: Correct docs - we no longer support change of basic proxy mode in the console app --- doc-src/features/reverseproxy.html | 3 --- doc-src/features/upstreamproxy.html | 3 --- 2 files changed, 6 deletions(-) (limited to 'doc-src') diff --git a/doc-src/features/reverseproxy.html b/doc-src/features/reverseproxy.html index e6de4f33..ea91fe1f 100644 --- a/doc-src/features/reverseproxy.html +++ b/doc-src/features/reverseproxy.html @@ -9,8 +9,5 @@ mitmproxy forwards HTTP proxy requests to an upstream proxy server. command-line -R http[s]://hostname[:port] - - mitmproxy shortcut P - diff --git a/doc-src/features/upstreamproxy.html b/doc-src/features/upstreamproxy.html index 6039f4df..bb354cd3 100644 --- a/doc-src/features/upstreamproxy.html +++ b/doc-src/features/upstreamproxy.html @@ -9,8 +9,5 @@ mitmproxy forwards ordinary HTTP requests to an upstream server. command-line -U http://hostname[:port] - - mitmproxy shortcut U - -- cgit v1.2.3 From 6bed0764609029e9d01b1d28b7826fb37ab20d3e Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Thu, 23 Oct 2014 16:13:03 +1300 Subject: Document http2https and https2http --- doc-src/features/reverseproxy.html | 17 ++++++++++++++++- doc-src/features/upstreamproxy.html | 14 ++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) (limited to 'doc-src') diff --git a/doc-src/features/reverseproxy.html b/doc-src/features/reverseproxy.html index ea91fe1f..1c57f0b2 100644 --- a/doc-src/features/reverseproxy.html +++ b/doc-src/features/reverseproxy.html @@ -7,7 +7,22 @@ mitmproxy forwards HTTP proxy requests to an upstream proxy server. - +
    command-line -R http[s]://hostname[:port]command-line -R schema://hostname[:port]
    + +Here, **schema** is one of http, https, http2https or https2http. The latter +two extended schema specifications control the use of HTTP and HTTPS on +mitmproxy and the upstream server. You can indicate that mitmproxy should use +HTTP, and the upstream server uses HTTPS like this: + + http2https://hostname:port + +And you can indicate that mitmproxy should use HTTPS while the upstream +service uses HTTP like this: + + https2http://hostname:port + + + diff --git a/doc-src/features/upstreamproxy.html b/doc-src/features/upstreamproxy.html index bb354cd3..47bc115d 100644 --- a/doc-src/features/upstreamproxy.html +++ b/doc-src/features/upstreamproxy.html @@ -11,3 +11,17 @@ mitmproxy forwards ordinary HTTP requests to an upstream server. + +Here, **schema** is one of http, https, http2https or https2http. The latter +two extended schema specifications control the use of HTTP and HTTPS on +mitmproxy and the upstream server. You can indicate that mitmproxy should use +HTTP, and the upstream server uses HTTPS like this: + + http2https://hostname:port + +And you can indicate that mitmproxy should use HTTPS while the upstream +service uses HTTP like this: + + https2http://hostname:port + + -- cgit v1.2.3 From bbee391a478c208861703e73339ab55935c07c5f Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Thu, 23 Oct 2014 16:14:04 +0200 Subject: update proxy modes diagrams --- doc-src/schematics/proxy-modes-transparent-1.png | Bin 16305 -> 14558 bytes doc-src/schematics/proxy-modes-transparent-2.png | Bin 23041 -> 23375 bytes .../schematics/proxy-modes-transparent-wrong.png | Bin 17568 -> 14719 bytes doc-src/schematics/proxy-modes.vsdx | Bin 195186 -> 190788 bytes 4 files changed, 0 insertions(+), 0 deletions(-) (limited to 'doc-src') diff --git a/doc-src/schematics/proxy-modes-transparent-1.png b/doc-src/schematics/proxy-modes-transparent-1.png index c2027432..002e0e76 100644 Binary files a/doc-src/schematics/proxy-modes-transparent-1.png and b/doc-src/schematics/proxy-modes-transparent-1.png differ diff --git a/doc-src/schematics/proxy-modes-transparent-2.png b/doc-src/schematics/proxy-modes-transparent-2.png index 1129e343..41997b05 100644 Binary files a/doc-src/schematics/proxy-modes-transparent-2.png and b/doc-src/schematics/proxy-modes-transparent-2.png differ diff --git a/doc-src/schematics/proxy-modes-transparent-wrong.png b/doc-src/schematics/proxy-modes-transparent-wrong.png index 6bac491f..ca501e93 100644 Binary files a/doc-src/schematics/proxy-modes-transparent-wrong.png and b/doc-src/schematics/proxy-modes-transparent-wrong.png differ diff --git a/doc-src/schematics/proxy-modes.vsdx b/doc-src/schematics/proxy-modes.vsdx index 74d425fc..c78cf8d0 100644 Binary files a/doc-src/schematics/proxy-modes.vsdx and b/doc-src/schematics/proxy-modes.vsdx differ -- cgit v1.2.3 From 4bf07d8aa5b137cf39282502cc960b88ba40a790 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Thu, 23 Oct 2014 16:15:38 +0200 Subject: fix typo --- doc-src/modes.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc-src') diff --git a/doc-src/modes.html b/doc-src/modes.html index 77bd1b05..ddbeae0c 100644 --- a/doc-src/modes.html +++ b/doc-src/modes.html @@ -198,7 +198,7 @@ This may work for the first request, but the HTML remains unchanged: As soon as

    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. +In upstream mode, all requests are unconditionally transferred to an upstream proxy of your choice.

    -- cgit v1.2.3 From e732771c1ca354ef7b895da4088e727573476e34 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Wed, 5 Nov 2014 09:57:09 +1300 Subject: We don't need requests for mitmproxy --- doc-src/install.html | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc-src') diff --git a/doc-src/install.html b/doc-src/install.html index 8a76e3ae..682e317e 100644 --- a/doc-src/install.html +++ b/doc-src/install.html @@ -1,6 +1,4 @@ - - ## Installing from source The preferred way to install mitmproxy - whether you're installing the latest -- cgit v1.2.3 From 8cbb67ac70772ac141fe1891e5fd47dd1cbc978c Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Thu, 13 Nov 2014 23:03:06 +0100 Subject: docs++ --- doc-src/ssl.html | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'doc-src') diff --git a/doc-src/ssl.html b/doc-src/ssl.html index 16aed1dc..3fa0e070 100644 --- a/doc-src/ssl.html +++ b/doc-src/ssl.html @@ -71,6 +71,15 @@ For example, you can generate a certificate in this format using these instructi +Using a custom certificate authority +------------------------------------ + +By default, mitmproxy will (generate and) use ~/.mitmproxy/mitmproxy-ca.pem as the default certificate +authority to generate certificates for all domains for which no custom certificate is provided (see above). +You can use your own certificate authority by passing the --confdir option to mitmproxy. +mitmproxy will then look for mitmproxy-ca.pem in the specified directory. If no such file exists, +it will be generated automatically. + Installing the mitmproxy CA --------------------------- -- cgit v1.2.3 From ffb95a1db742d71d7671f9e9c6db552774bb0ead Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Tue, 9 Dec 2014 00:01:01 +0100 Subject: fix #304 --- doc-src/features/reverseproxy.html | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'doc-src') diff --git a/doc-src/features/reverseproxy.html b/doc-src/features/reverseproxy.html index 1c57f0b2..5ef4efc5 100644 --- a/doc-src/features/reverseproxy.html +++ b/doc-src/features/reverseproxy.html @@ -25,4 +25,28 @@ service uses HTTP like this: https2http://hostname:port - +### Host Header + +In reverse proxy mode, mitmproxy does not rewrite the host header. While often useful, this +may lead to issues with public web servers. For example, consider the following scenario: + + $ python mitmdump -d -R http://example.com/ & + $ curl http://localhost:8080/ + + >> GET https://example.com/ + Host: localhost:8080 + User-Agent: curl/7.35.0 + [...] + + << 404 Not Found 345B + +Since the Host header doesn't match example.com, an error is returned.
    +There are two ways to solve this: +
      +
    1. Modify the hosts file of your OS so that example.com resolves to 127.0.0.1.
      2. +
    2. + Instruct mitmproxy to rewrite the host header by passing ‑‑setheader :~q:Host:example.com. + However, keep in mind that absolute URLs within the returned document or HTTP redirects will cause the client application + to bypass the proxy. +
      3. +
    \ No newline at end of file -- cgit v1.2.3