diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/certinstall.rst | 10 | ||||
| -rw-r--r-- | docs/features/passthrough.rst | 6 | ||||
| -rw-r--r-- | docs/index.rst | 10 | ||||
| -rw-r--r-- | docs/protocols/http1.rst | 15 | ||||
| -rw-r--r-- | docs/protocols/http2.rst | 16 | ||||
| -rw-r--r-- | docs/protocols/tcpproxy.rst (renamed from docs/features/tcpproxy.rst) | 6 | ||||
| -rw-r--r-- | docs/protocols/websocket.rst | 22 | ||||
| -rw-r--r-- | docs/scripting/api.rst | 12 | ||||
| -rw-r--r-- | docs/scripting/events.rst | 14 | ||||
| -rw-r--r-- | docs/transparent/linux.rst | 12 | ||||
| -rw-r--r-- | docs/transparent/osx.rst | 3 |
11 files changed, 101 insertions, 25 deletions
diff --git a/docs/certinstall.rst b/docs/certinstall.rst index 2ec5f022..6662e34d 100644 --- a/docs/certinstall.rst +++ b/docs/certinstall.rst @@ -24,10 +24,6 @@ something like this: Click on the relevant icon, follow the setup instructions for the platform you're on and you are good to go. -For iOS version 10.3 or up, you need to make sure ``mitmproxy`` is enabled in -``Certificate Trust Settings``, you can check it by going to -``Settings > General > About > Certificate Trust Settings``. - Installing the mitmproxy CA certificate manually ------------------------------------------------ @@ -39,7 +35,6 @@ documentation for some common platforms. The mitmproxy CA cert is located in ``~/.mitmproxy`` after it has been generated at the first start of mitmproxy. - iOS ^^^ @@ -47,6 +42,11 @@ See http://jasdev.me/intercepting-ios-traffic and https://web.archive.org/web/20150920082614/http://kb.mit.edu/confluence/pages/viewpage.action?pageId=152600377 +On iOS 10.3 and onwards, you also need to enable full trust for the mitmproxy root certificate: + +1. Go to Settings > General > About > Certificate Trust Settings. +2. Under "Enable full trust for root certificates", turn on trust for the mitmproxy certificate. + iOS Simulator ^^^^^^^^^^^^^ diff --git a/docs/features/passthrough.rst b/docs/features/passthrough.rst index 00462e9d..91fcb9b6 100644 --- a/docs/features/passthrough.rst +++ b/docs/features/passthrough.rst @@ -13,7 +13,7 @@ mechanism: away. Note that mitmproxy's "Limit" option is often the better alternative here, as it is not affected by the limitations listed below. -If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcpproxy` +If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcp_proxy` feature. If you want to ignore traffic from mitmproxy's processing because of large response bodies, take a look at the :ref:`streaming` feature. @@ -38,7 +38,7 @@ There are two important quirks to consider: - **In transparent mode, the ignore pattern is matched against the IP and ClientHello SNI host.** 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. If the client uses SNI however, then we treat the SNI host as an ignore target. -- **In regular mode, explicit HTTP requests are never ignored.** [#explicithttp]_ The ignore pattern is +- **In regular and upstream proxy 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 @@ -88,7 +88,7 @@ Here are some other examples for ignore patterns: .. seealso:: - - :ref:`tcpproxy` + - :ref:`tcp_proxy` - :ref:`streaming` - mitmproxy's "Limit" feature diff --git a/docs/index.rst b/docs/index.rst index 7cf593ff..8dba4d04 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,15 @@ .. toctree:: :hidden: + :caption: Protocols + + protocols/http1 + protocols/http2 + protocols/websocket + protocols/tcpproxy + +.. toctree:: + :hidden: :caption: Features features/anticache @@ -36,7 +45,6 @@ features/streaming features/socksproxy features/sticky - features/tcpproxy features/upstreamproxy features/upstreamcerts diff --git a/docs/protocols/http1.rst b/docs/protocols/http1.rst new file mode 100644 index 00000000..21e68785 --- /dev/null +++ b/docs/protocols/http1.rst @@ -0,0 +1,15 @@ +.. _http1_protocol: + +HTTP/1.0 and HTTP/1.1 +=========================== + +.. seealso:: + + - `RFC7230: HTTP/1.1: Message Syntax and Routing <http://tools.ietf.org/html/rfc7230>`_ + - `RFC7231: HTTP/1.1: Semantics and Content <http://tools.ietf.org/html/rfc7231>`_ + +HTTP/1.0 and HTTP/1.1 support in mitmproxy is based on our custom HTTP stack, +which takes care of all semantics and on-the-wire parsing/serialization tasks. + +mitmproxy currently does not support HTTP trailers - but if you want to send +us a PR, we promise to take look! diff --git a/docs/protocols/http2.rst b/docs/protocols/http2.rst new file mode 100644 index 00000000..b3268ae5 --- /dev/null +++ b/docs/protocols/http2.rst @@ -0,0 +1,16 @@ +.. _http2_protocol: + +HTTP/2 +====== + +.. seealso:: + + - `RFC7540: Hypertext Transfer Protocol Version 2 (HTTP/2) <http://tools.ietf.org/html/rfc7540>`_ + +HTTP/2 support in mitmproxy is based on the amazing work by the python-hyper +community with the `hyper-h2 <https://github.com/python-hyper/hyper-h2>`_ +project. It fully encapsulates the internal state of HTTP/2 connections and +provides an easy-to-use event-based API. + +mitmproxy currently does not support HTTP/2 trailers - but if you want to send +us a PR, we promise to take look! diff --git a/docs/features/tcpproxy.rst b/docs/protocols/tcpproxy.rst index cba374e3..77248573 100644 --- a/docs/features/tcpproxy.rst +++ b/docs/protocols/tcpproxy.rst @@ -1,7 +1,7 @@ -.. _tcpproxy: +.. _tcp_proxy: -TCP Proxy -========= +TCP Proxy / Fallback +==================== In case mitmproxy does not handle a specific protocol, you can exempt hostnames from processing, so that mitmproxy acts as a generic TCP forwarder. diff --git a/docs/protocols/websocket.rst b/docs/protocols/websocket.rst new file mode 100644 index 00000000..8a7e807f --- /dev/null +++ b/docs/protocols/websocket.rst @@ -0,0 +1,22 @@ +.. _websocket_protocol: + +WebSocket +========= + +.. seealso:: + + - `RFC6455: The WebSocket Protocol <http://tools.ietf.org/html/rfc6455>`_ + - `RFC7692: Compression Extensions for WebSocket <http://tools.ietf.org/html/rfc7692>`_ + +WebSocket support in mitmproxy is based on the amazing work by the python-hyper +community with the `wsproto <https://github.com/python-hyper/wsproto>`_ +project. It fully encapsulates WebSocket frames/messages/connections and +provides an easy-to-use event-based API. + +mitmproxy fully supports the compression extension for WebSocket messages, +provided by wsproto. + +If an endpoint sends a PING to mitmproxy, a PONG will be sent back immediately +(with the same payload if present). To keep the other connection alive, a new +PING (without a payload) is sent to the other endpoint. Unsolicited PONG's are +not forwarded. All PING's and PONG's are logged (with payload if present). diff --git a/docs/scripting/api.rst b/docs/scripting/api.rst index e82afef4..368b9ba8 100644 --- a/docs/scripting/api.rst +++ b/docs/scripting/api.rst @@ -10,6 +10,9 @@ API - `mitmproxy.http.HTTPRequest <#mitmproxy.http.HTTPRequest>`_ - `mitmproxy.http.HTTPResponse <#mitmproxy.http.HTTPResponse>`_ - `mitmproxy.http.HTTPFlow <#mitmproxy.http.HTTPFlow>`_ +- WebSocket + - `mitmproxy.websocket.WebSocketFlow <#mitmproxy.websocket.WebSocketFlow>`_ + - `mitmproxy.websocket.WebSocketMessage <#mitmproxy.websocket.WebSocketMessage>`_ - Logging - `mitmproxy.log.Log <#mitmproxy.controller.Log>`_ - `mitmproxy.log.LogEntry <#mitmproxy.controller.LogEntry>`_ @@ -33,6 +36,15 @@ HTTP .. autoclass:: mitmproxy.http.HTTPFlow :inherited-members: +WebSocket +--------- + +.. autoclass:: mitmproxy.websocket.WebSocketFlow + :inherited-members: + +.. autoclass:: mitmproxy.websocket.WebSocketMessage + :inherited-members: + Logging -------- diff --git a/docs/scripting/events.rst b/docs/scripting/events.rst index 8f9463ff..d8b1fbb8 100644 --- a/docs/scripting/events.rst +++ b/docs/scripting/events.rst @@ -100,10 +100,10 @@ HTTP Events * - .. py:function:: http_connect(flow) - Called when we receive an HTTP CONNECT request. Setting a non 2xx - response on the flow will return the response to the client abort the - connection. CONNECT requests and responses do not generate the usual - HTTP handler events. CONNECT requests are only valid in regular and - upstream proxy modes. + response on the flow will return the response to the client and abort + the connection. CONNECT requests and responses do not generate the + usual HTTP handler events. CONNECT requests are only valid in regular + and upstream proxy modes. *flow* A ``models.HTTPFlow`` object. The flow is guaranteed to have @@ -187,8 +187,8 @@ are issued, only new WebSocket messages are called. - Called when a WebSocket message is received from the client or server. The sender and receiver are identifiable. The most recent message will be - ``flow.messages[-1]``. The message is user-modifiable. Currently there are - two types of messages, corresponding to the BINARY and TEXT frame types. + ``flow.messages[-1]``. The message is user-modifiable and is killable. + A message is either of TEXT or BINARY type. *flow* A ``models.WebSocketFlow`` object. @@ -211,7 +211,7 @@ TCP Events ---------- These events are called only if the connection is in :ref:`TCP mode -<tcpproxy>`. So, for instance, TCP events are not called for ordinary HTTP/S +<tcp_proxy>`. So, for instance, TCP events are not called for ordinary HTTP/S connections. .. list-table:: diff --git a/docs/transparent/linux.rst b/docs/transparent/linux.rst index 1878008c..14f6a165 100644 --- a/docs/transparent/linux.rst +++ b/docs/transparent/linux.rst @@ -11,16 +11,16 @@ achieve transparent mode. 2. Enable IP forwarding: >>> sysctl -w net.ipv4.ip_forward=1 + >>> sysctl -w net.ipv6.conf.all.forwarding=1 - You may also want to consider enabling this permanently in ``/etc/sysctl.conf``. + You may also want to consider enabling this permanently in ``/etc/sysctl.conf`` or newly created ``/etc/sysctl.d/mitmproxy.conf``, see `here <https://superuser.com/a/625852>`__. 3. If your target machine is on the same physical network and you configured it to use a custom gateway, disable ICMP redirects: - >>> echo 0 | sudo tee /proc/sys/net/ipv4/conf/*/send_redirects + >>> sysctl -w net.ipv4.conf.all.send_redirects=0 - You may also want to consider enabling this permanently in ``/etc/sysctl.conf`` - as demonstrated `here <https://unix.stackexchange.com/a/58081>`_. + You may also want to consider enabling this permanently in ``/etc/sysctl.conf`` or a newly created ``/etc/sysctl.d/mitmproxy.conf``, see `here <https://superuser.com/a/625852>`__. 4. Create an iptables ruleset that redirects the desired traffic to the mitmproxy port. Details will differ according to your setup, but the @@ -30,6 +30,10 @@ achieve transparent mode. 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 + ip6tables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080 + ip6tables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080 + + You may also want to consider enabling this permanently with the ``iptables-persistent`` package, see `here <http://www.microhowto.info/howto/make_the_configuration_of_iptables_persistent_on_debian.html>`__. 5. Fire up mitmproxy. You probably want a command like this: diff --git a/docs/transparent/osx.rst b/docs/transparent/osx.rst index 40e91fac..5d4ec612 100644 --- a/docs/transparent/osx.rst +++ b/docs/transparent/osx.rst @@ -17,8 +17,7 @@ Note that this means we don't support transparent mode for earlier versions of O .. code-block:: none - rdr on en2 inet proto tcp to any port 80 -> 127.0.0.1 port 8080 - rdr on en2 inet proto tcp to any port 443 -> 127.0.0.1 port 8080 + rdr on en0 inet proto tcp to any port {80, 443} -> 127.0.0.1 port 8080 These rules tell pf to redirect all traffic destined for port 80 or 443 to the local mitmproxy instance running on port 8080. You should |