<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
<link href="01-bootstrap.min.css" type="text/css" rel="StyleSheet"/>
<link href="02-docstyle.css" type="text/css" rel="StyleSheet"/>
<link href="syntax.css" type="text/css" rel="StyleSheet"/>
<title>mitmproxy 0.9 - mitmproxy</title></head><body><div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="index.html">mitmproxy 0.9 docs</a>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="span3">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li><a href="index.html">Introduction</a></li>
<li><a href="install.html">Installation</a></li>
<li><a href="howmitmproxy.html">How mitmproxy works</a></li>
<li class="nav-header">Tools</li>
<li class="active"><a href="mitmproxy.html">mitmproxy</a></li>
<li><a href="mitmdump.html">mitmdump</a></li>
<li class="nav-header">Features</li>
<li><a href="features/anticache.html">Anticache</a></li>
<li><a href="features/clientreplay.html">Client-side replay</a></li>
<li><a href="features/filters.html">Filter expressions</a></li>
<li><a href="features/proxyauth.html">Proxy Authentication</a></li>
<li><a href="features/replacements.html">Replacements</a></li>
<li><a href="features/serverreplay.html">Server-side replay</a></li>
<li><a href="features/setheaders.html">Set Headers</a></li>
<li><a href="features/sticky.html">Sticky cookies and auth</a></li>
<li><a href="features/reverseproxy.html">Reverse proxy mode</a></li>
<li><a href="features/upstreamcerts.html">Upstream Certs</a></li>
<li class="nav-header">Installing Certificates</li>
<li><a href="ssl.html">Overview</a></li>
<li><a href="certinstall/firefox.html">Firefox</a></li>
<li><a href="certinstall/osx.html">OSX</a></li>
<li><a href="certinstall/windows7.html">Windows 7</a></li>
<li><a href="certinstall/ios.html">IOS</a></li>
<li><a href="certinstall/ios-simulator.html">IOS Simulator</a></li>
<li><a href="certinstall/android.html">Android</a></li>
<li class="nav-header">Transparent Proxying</li>
<li><a href="transparent.html">Overview</a></li>
<li><a href="transparent/linux.html">Linux</a></li>
<li><a href="transparent/osx.html">OSX</a></li>
<li class="nav-header">Tutorials</li>
<li><a href="tutorials/30second.html">Client playback: a 30 second example</a></li>
<li><a href="tutorials/gamecenter.html">Setting highscores on Apple's GameCenter</a></li>
<li class="nav-header">Scripting mitmproxy</li>
<li><a href="scripting/inlinescripts.html">Inline Scripts</a></li>
<li><a href="scripting/libmproxy.html">libmproxy</a></li>
<li class="nav-header">Hacking</li>
<li><a href="dev/testing.html">Testing</a></li>
</ul>
</div>
</div>
<div class="span9">
<div class="page-header">
<h1>mitmproxy</h1>
</div>
<p><strong>mitmproxy</strong> is a console tool that allows interactive examination and
modification of HTTP traffic. It differs from mitmdump in that all flows are
kept in memory, which means that it's intended for taking and manipulating
small-ish samples. Use the <em>?</em> shortcut key to view, context-sensitive
documentation from any <strong>mitmproxy</strong> screen.</p>
<h2>Flow list</h2>
<p>The flow list shows an index of captured flows in chronological order. </p>
<p><img src="screenshots/mitmproxy.png"/></p>
<ul>
<li><strong>1</strong>: A GET request, returning a 302 Redirect response.</li>
<li><strong>2</strong>: A GET request, returning 16.75kb of text/html data.</li>
<li><strong>3</strong>: A replayed request. </li>
<li><strong>4</strong>: Intercepted flows are indicated with orange text. The user may edit
these flows, and then accept them (using the <em>a</em> key) to continue. In this
case, the request has been intercepted on the way to the server.</li>
<li><strong>5</strong>: A response intercepted from the server on the way to the client.</li>
<li><strong>6</strong>: The event log can be toggled on and off using the <em>e</em> shortcut key. This
pane shows events and errors that may not result in a flow that shows up in the
flow pane.</li>
<li><strong>7</strong>: Flow count.</li>
<li><strong>8</strong>: Various information on mitmproxy's state. In this case, we have an
interception pattern set to ".*".</li>
<li><strong>9</strong>: Bind address indicator - mitmproxy is listening on port 8080 of all
interfaces.</li>
</ul>
<h2>Flow view</h2>
<p>The <strong>Flow View</strong> lets you inspect and manipulate a single flow:</p>
<p><img src="screenshots/mitmproxy-flowview.png"/></p>
<ul>
<li><strong>1</strong>: Flow summary.</li>
<li><strong>2</strong>: The Request/Response tabs, showing you which part of the flow you are
currently viewing. In the example above, we're viewing the Response. Hit <em>tab</em>
to switch between the Response and the Request.</li>
<li><strong>3</strong>: Headers.</li>
<li><strong>4</strong>: Body.</li>
<li><strong>5</strong>: View Mode indicator. In this case, we're viewing the body in <strong>hex</strong>
mode. The other available modes are <strong>pretty</strong>, which uses a number of
heuristics to show you a friendly view of various content types, and <strong>raw</strong>,
which shows you exactly what's there without any changes. You can change modes
using the <em>m</em> key.</li>
</ul>
<h2>Grid Editor</h2>
<p>Much of the data that we'd like to interact with in mitmproxy is structured.
For instance, headers, queries and form data can all be thought of as a list of
key/value pairs. Mitmproxy has a built-in editor that lays this type of data
out in a grid for easy manipulation. </p>
<p>At the moment, the Grid Editor is used in four parts of mitmproxy:</p>
<ul>
<li>Editing request or response headers (<em>e</em> for edit, then <em>h</em> for headers in flow view) </li>
<li>Editing a query string (<em>e</em> for edit, then <em>q</em> for query in flow view)</li>
<li>Editing a URL-encoded form (<em>e</em> for edit, then <em>f</em> for form in flow view)</li>
<li>Editing replacement patterns (<em>R</em> globally)</li>
</ul>
<p>If there is is no data, an empty editor will be started to let you add some.
Here is the editor showing the headers from a request:</p>
<p><img src="screenshots/mitmproxy-kveditor.png"/></p>
<p>To edit, navigate to the key or value you want to modify using the arrow or vi
navigation keys, and press enter. The background color will change to show that
you are in edit mode for the specified field:</p>
<p><img src="screenshots/mitmproxy-kveditor-editmode.png"/></p>
<p>Modify the field as desired, then press escape to exit edit mode when you're
done. You can also add a row (<em>a</em> key), delete a row (<em>d</em> key), spawn an
external editor on a field (<em>e</em> key). Be sure to consult the context-sensitive
help (<em>?</em> key) for more.</p>
<h1>Example: Interception</h1>
<p><strong>mitmproxy</strong>'s interception functionality lets you pause an HTTP request or
response, inspect and modify it, and then accept it to send it on to the server
or client. </p>
<h3>1: Set an interception pattern</h3>
<p><img src="screenshots/mitmproxy-intercept-filt.png"/></p>
<p>We press <em>i</em> to set an interception pattern. In this case, the <strong>~q</strong> filter
pattern tells <strong>mitmproxy</strong> to intercept all requests. For complete filter
syntax, see the <a href="features/filters.html">Filter expressions</a> section of this
document, or the built-in help function in <strong>mitmproxy</strong>.</p>
<h3>2: Intercepted connections are indicated with orange text:</h3>
<p><img src="screenshots/mitmproxy-intercept-mid.png"/></p>
<h3>3: You can now view and modify the request:</h3>
<p><img src="screenshots/mitmproxy-intercept-options.png"/></p>
<p>In this case, we viewed the request by selecting it, pressed <em>e</em> for "edit"
and <em>m</em> for "method" to change the HTTP request method.</p>
<h3>4: Accept the intercept to continue:</h3>
<p><img src="screenshots/mitmproxy-intercept-result.png"/></p>
<p>Finally, we press <em>a</em> to accept the modified request, which is then sent on to
the server. In this case, we changed the request from an HTTP GET to
OPTIONS, and Google's server has responded with a 405 "Method not allowed". </p>
</div>
</div>
<hr>
<footer>
<p>© mitmproxy project, 2013</p>
</footer>
</div>
</body></html>
