diff options
Diffstat (limited to 'doc-src')
| -rw-r--r-- | doc-src/_nav.html | 1 | ||||
| -rw-r--r-- | doc-src/features/index.py | 1 | ||||
| -rw-r--r-- | doc-src/features/passthrough.html | 12 | ||||
| -rw-r--r-- | doc-src/features/responsestreaming.html | 6 | ||||
| -rw-r--r-- | doc-src/features/tcpproxy.html | 30 | ||||
| -rw-r--r-- | doc-src/install.html | 19 | ||||
| -rw-r--r-- | doc-src/scripting/inlinescripts.html | 11 | ||||
| -rw-r--r-- | doc-src/ssl.html | 22 | ||||
| -rw-r--r-- | doc-src/transparent/linux.html | 10 |
9 files changed, 102 insertions, 10 deletions
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 </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.
\ 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 (<code>libmproxy.protocol.http.CONTENT_MISSING</code>). Any modifications will be ignored. Streamed responses are usually sent in chunks of 4096 bytes. If the response is sent with a <code>Transfer-Encoding: - chunked</code> header, the response will be streamed one chunk at a time.
\ No newline at end of file + chunked</code> 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 + + +<table class="table"> + <tbody> + <tr> + <th width="20%">command-line</th> <td>--tcp HOST</td> + </tr> + <tr> + <th>mitmproxy shortcut</th> <td><b>T</b></td> + </tr> + </tbody> +</table> + +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")!@) diff --git a/doc-src/install.html b/doc-src/install.html index 70003d60..5d412459 100644 --- a/doc-src/install.html +++ b/doc-src/install.html @@ -50,3 +50,22 @@ image/*; /usr/bin/open -Wn %s video/*; /usr/bin/open -Wn %s </pre> + +## Ubuntu + +On Ubuntu, you will need the following native packages to install mitmproxy +from source: + +- build-essential +- python-dev +- libffi-dev +- libssl-dev +- libxml2-dev +- libxslt1-dev + + + + + + + diff --git a/doc-src/scripting/inlinescripts.html b/doc-src/scripting/inlinescripts.html index eef4e440..2c3e0d6f 100644 --- a/doc-src/scripting/inlinescripts.html +++ b/doc-src/scripting/inlinescripts.html @@ -21,6 +21,12 @@ We can now run this script using mitmdump or mitmproxy as follows: The new header will be added to all responses passing through the proxy. +## Example Scripts + +mitmproxy comes with a variety of example inline scripts, which demonstrate +many basic tasks. We encourage you to either browse them locally or in our +[GitHub repo](https://github.com/mitmproxy/mitmproxy/tree/master/examples). + ## Events @@ -129,8 +135,9 @@ The main classes you will deal with in writing mitmproxy scripts are: </tr> </table> -The canonical API documentation is the code. You can view the API documentation -using pydoc (which is installed with Python by default), like this: +The canonical API documentation is the code, which you can browse locally or in our +[GitHub repo](https://github.com/mitmproxy/mitmproxy). +You can view the API documentation using pydoc (which is installed with Python by default), like this: <pre class="terminal"> > pydoc libmproxy.protocol.http.HTTPRequest 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 <kbd>--cert</kbd> 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: + +<pre> +-----BEGIN PRIVATE KEY----- +<private key> +-----END PRIVATE KEY----- +-----BEGIN CERTIFICATE----- +<cert> +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +<intermediary cert (optional)> +-----END CERTIFICATE----- +</pre> + +For example, you can generate a certificate in this format using these instructions: <pre class="terminal"> > openssl genrsa -out cert.key 8192 diff --git a/doc-src/transparent/linux.html b/doc-src/transparent/linux.html index 96b7132a..7c01931d 100644 --- a/doc-src/transparent/linux.html +++ b/doc-src/transparent/linux.html @@ -15,6 +15,16 @@ achieve transparent mode. </li> + <li> If your target machine is on the same physical network and you configured it to use a custom gateway, + disable ICMP redirects: + + <pre class="terminal">echo 0 | sudo tee /proc/sys/net/ipv4/conf/*/send_redirects</pre> + + You may also want to consider enabling this permanently in + <b>/etc/sysctl.conf</b> as demonstrated <a href="http://unix.stackexchange.com/a/58081">here</a>. + + </li> + <li> 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: |