From b5cf3b4f743f1dd3e7d58c9d21155005466640ec Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Tue, 14 May 2013 09:12:26 +1200 Subject: [PATCH] README, Linux transparent mode docs, requirements additions. --- README.mkd | 9 ++++++++ doc-src/transparent.html | 18 +++++++++------ doc-src/transparent/index.py | 2 +- doc-src/transparent/linux.html | 40 ++++++++++++++++++++++++++++++++++ setup.py | 3 ++- 5 files changed, 63 insertions(+), 9 deletions(-) diff --git a/README.mkd b/README.mkd index dcb678110..a711d506c 100644 --- a/README.mkd +++ b/README.mkd @@ -35,6 +35,12 @@ Requirements * [urwid](http://excess.org/urwid/) version 1.1 or newer. * [PIL](http://www.pythonware.com/products/pil/) version 1.1 or newer. * [lxml](http://lxml.de/) version 2.3 or newer. +* [flask](http://flask.pocoo.org/) version 0.9 or newer. + +Optional, for extended content decoding: + +* [PyAMF](http://www.pyamf.org/) version 0.6.1 or newer. +* [protobuf](https://code.google.com/p/protobuf/) version 2.5.0 or newer. __mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. Windows is not officially supported at the moment. @@ -49,3 +55,6 @@ The following components are needed if you plan to hack on mitmproxy: framework and requires [pathod](http://pathod.org) and [flask](http://flask.pocoo.org/). * Rendering the documentation requires [countershape](http://github.com/cortesi/countershape). +Please ensure that all patches are accompanied by matching changes in the test +suite. The project maintains 100% test coverage. + diff --git a/doc-src/transparent.html b/doc-src/transparent.html index 689a28425..4e9b6774c 100644 --- a/doc-src/transparent.html +++ b/doc-src/transparent.html @@ -1,15 +1,19 @@ - -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 - proxy-oblivious Android applications being a common -example. +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 - proxy-oblivious Android applications being a common example. To set up transparent proxying, we need two new components. The first is a redirection mechanism that transparently reroutes a TCP connection destined for a server on the Internet to a listening proxy server. This usually takes the form of a firewall on the same host as the proxy server - [iptables](http://www.netfilter.org/) on Linux or -[pf](http://en.wikipedia.org/wiki/PF_\(firewall\)) on OSX. When the proxy receives a redirected connection, it sees a vanilla HTTP request, without a host specification. This is where the second new component comes in - a host module that allows us to query the redirector for the original destination of the TCP connection. +[pf](http://en.wikipedia.org/wiki/PF_\(firewall\)) on OSX. When the proxy +receives a redirected connection, it sees a vanilla HTTP request, without a +host specification. This is where the second new component comes in - a host +module that allows us to query the redirector for the original destination of +the TCP connection. -At the moment, mitmproxy supports transparent proxying on OSX Lion and above, and all current flavors of Linux.kkkkk \ No newline at end of file +At the moment, mitmproxy supports transparent proxying on OSX Lion and above, +and all current flavors of Linux. diff --git a/doc-src/transparent/index.py b/doc-src/transparent/index.py index d277d7080..091b34717 100644 --- a/doc-src/transparent/index.py +++ b/doc-src/transparent/index.py @@ -1,6 +1,6 @@ from countershape import Page pages = [ - Page("linux.html", "Linux"), Page("osx.html", "OSX"), + Page("linux.html", "Linux"), ] diff --git a/doc-src/transparent/linux.html b/doc-src/transparent/linux.html index e69de29bb..41840c752 100644 --- a/doc-src/transparent/linux.html +++ b/doc-src/transparent/linux.html @@ -0,0 +1,40 @@ +On Linux, mitmproxy integrates with the iptables redirection mechanism to +achieve transparent mode. + +
    + +
  1. Install the mitmproxy + certificates on the test device.
    2. + +
  2. Enable IP forwarding: + + 
    sysctl -w net.ipv4.ip_forward=1
    + + You may also want to consider enabling this permanently in + /etc/sysctl.conf. + +
    3. + +
  3. Create an iptables ruleset that redirects the desired traffic to the + mitmproxy port. Details will differ according to your setup, but the + ruleset should look something like this: + +
    iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
+iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080
    + +
    4. + +
  4. Fire up mitmproxy. You probably want a command like this: + + 
    mitmproxy -T --host
    + + The -T flag turns on transparent mode, and the --host + argument tells mitmproxy to use the value of the Host header for URL + display. + +
    5. + +
  5. Finally, configure your test device to use the host on which mitmproxy is + running as the default gateway.
    6. + +
diff --git a/setup.py b/setup.py index c0b957289..2ba8ba668 100644 --- a/setup.py +++ b/setup.py @@ -98,6 +98,7 @@ setup( "pyasn1>0.1.2", "pyopenssl>=0.12", "PIL", - "lxml" + "lxml", + "flask" ], )