CINXE.COM
Introduction
<!DOCTYPE html> <html lang="en-us"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <link rel="icon" type="image/png" href="./favicon.ico"> <title>Introduction</title> <link rel="stylesheet" href="./style.min.css"> <link rel="alternate" type="application/rss+xml" href="./index.xml" title="mitmproxy.org docs" /> <meta name="generator" content="Hugo 0.139.3"> </head> <body> <div class="columns container is-marginless"> <div id="sidebar" class="column is-one-quarter"> <div class="brand"> <a href="https://mitmproxy.org/"> <img src='./logo-docs.png' alt="mitmproxy docs"/> </a> </div> <nav class="menu"> <p class="menu-label">Overview</p> <ul class="menu-list"> <li> <a class="is-active" href="./">Introduction</a> </li> <li> <a class="" href="./overview-installation/">Installation</a> </li> <li> <a class="" href="./overview-getting-started/">Getting Started</a> </li> </ul> <p class="menu-label">Beginner Tutorial (CLI)</p> <ul class="menu-list"> <li> <a class="" href="./mitmproxytutorial-userinterface/">User Interface</a> </li> <li> <a class="" href="./mitmproxytutorial-interceptrequests/">Intercept Requests</a> </li> <li> <a class="" href="./mitmproxytutorial-modifyrequests/">Modify Requests</a> </li> <li> <a class="" href="./mitmproxytutorial-replayrequests/">Replay Requests</a> </li> <li> <a class="" href="./mitmproxytutorial-whatsnext/">What's Next</a> </li> </ul> <p class="menu-label">Beginner Tutorial (Web)</p> <ul class="menu-list"> <li> <a class="" href="./web-tutorials/web-01-user-interface/">User Interface</a> </li> <li> <a class="" href="./web-tutorials/web-02-intercepting-traffic/">Intercept Traffic</a> </li> <li> <a class="" href="./web-tutorials/web-03-analysing-flows/">Analyze Flows</a> </li> <li> <a class="" href="./web-tutorials/web-04-modifying-requests/">Modify Requests</a> </li> <li> <a class="" href="./web-tutorials/web-05-replaying-flows/">Replay Flows</a> </li> </ul> <p class="menu-label">Core concepts</p> <ul class="menu-list"> <li> <a class="" href="./concepts-howmitmproxyworks/">How mitmproxy works</a> </li> <li> <a class="" href="./concepts-modes/">Proxy Modes</a> </li> <li> <a class="" href="./concepts-certificates/">Certificates</a> </li> <li> <a class="" href="./overview-features/">Features</a> </li> <li> <a class="" href="./concepts-filters/">Filter expressions</a> </li> <li> <a class="" href="./concepts-options/">Options</a> </li> <li> <a class="" href="./concepts-commands/">Commands</a> </li> <li> <a class="" href="./concepts-protocols/">Protocols</a> </li> </ul> <p class="menu-label"> Addon Development </p> <ul class="menu-list"> <li> <a class="" href="./addons-overview/">Addons</a> </li> <li> <a class="" href="./api/events.html">Event Hooks & API</a> </li> <li> <a class="" href="./addons-options/">Options</a> </li> <li> <a class="" href="./addons-commands/">Commands</a> </li> <li> <a class="" href="./addons-examples/">Examples</a> </li> <li> <a class="" href="./addons-api-changelog/">API Changelog</a> </li> </ul> <p class="menu-label"> HOWTOs </p> <ul class="menu-list"> <li> <a class="" href="./howto-kubernetes/">Kubernetes Services</a> </li> <li> <a class="" href="./howto-transparent/">Transparent Proxying</a> </li> <li> <a class="" href="./howto-wireshark-tls/">Wireshark and SSL/TLS</a> </li> <li> <a class="" href="./howto-ignoredomains/">Ignoring Domains</a> </li> <li> <a class="" href="./howto-transparent-vms/">Transparently Proxying VMs</a> </li> <li> <a class="" href="./howto-install-system-trusted-ca-android/">System CA on Android Emulator</a> </li> </ul> <p class="menu-label"> Tutorials </p> <ul class="menu-list"> <li> <a class="" href="./tute-clientreplay/">Client replay</a> </li> <li> <a class="" href="./tute-highscores/">Setting highscores on Apple GameCenter</a> </li> </ul> </nav> </div> <div id="main" class="column content"> <h1 id="introduction"><a class="anchor" href="#introduction"># </a>Introduction</h1> <p>mitmproxy is a set of tools that provide an interactive, SSL/TLS-capable intercepting proxy for HTTP/1, HTTP/2, and WebSockets.</p> <h2 id="features"><a class="anchor" href="#features"># </a>Features</h2> <ul> <li>Intercept HTTP & HTTPS requests and responses and modify them on the fly</li> <li>Save complete HTTP conversations for later replay and analysis</li> <li>Replay the client-side of an HTTP conversation</li> <li>Replay HTTP responses of a previously recorded server</li> <li>Reverse proxy mode to forward traffic to a specified server</li> <li>Transparent proxy mode on macOS and Linux</li> <li>Make scripted changes to HTTP traffic using Python</li> <li>SSL/TLS certificates for interception are generated on the fly</li> <li>And <a href="./overview-features/">much, much more…</a></li> </ul> <h2 id="3-powerful-core-tools"><a class="anchor" href="#3-powerful-core-tools"># </a>3 Powerful Core Tools</h2> <p>The mitmproxy project’s tools are a set of front-ends that expose common underlying functionality. When we talk about “mitmproxy” we usually refer to any of the three tools - they are just different front-ends to the same core proxy.</p> <p><strong>mitmproxy</strong> is an interactive, SSL/TLS-capable intercepting proxy with a console interface for HTTP/1, HTTP/2, and WebSockets.</p> <p><strong>mitmweb</strong> is a web-based interface for mitmproxy.</p> <p><strong>mitmdump</strong> is the command-line version of mitmproxy. Think tcpdump for HTTP.</p> <p>Distribution packages can be found on the <a href="https://mitmproxy.org">mitmproxy website</a>. Development information and our source code can be found in our <a href="https://github.com/mitmproxy/mitmproxy">GitHub repository</a>.</p> <h3 id="mitmproxy"><a class="anchor" href="#mitmproxy"># </a>mitmproxy</h3> <figure><img src="./screenshots/mitmproxy.png"> </figure> <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 <code>?</code> shortcut key to view, context-sensitive documentation from any <strong>mitmproxy</strong> screen.</p> <hr> <h3 id="mitmweb"><a class="anchor" href="#mitmweb"># </a>mitmweb</h3> <figure><img src="./screenshots/mitmweb.png"> </figure> <p><strong>mitmweb</strong> is mitmproxy’s web-based user interface that allows interactive examination and modification of HTTP traffic. Like mitmproxy, 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.</p> <div class="notification is-info">Mitmweb is currently in beta. We consider it stable for all features currently exposed in the UI, but it still misses a lot of mitmproxy’s features.</div> <hr> <h3 id="mitmdump"><a class="anchor" href="#mitmdump"># </a>mitmdump</h3> <p><strong>mitmdump</strong> is the command-line companion to mitmproxy. It provides tcpdump-like functionality to let you view, record, and programmatically transform HTTP traffic. See the <code>--help</code> flag output for complete documentation.</p> <h4 id="example-saving-traffic"><a class="anchor" href="#example-saving-traffic"># </a>Example: Saving traffic</h4> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mitmdump -w outfile </span></span></code></pre></div><p>Start up mitmdump in proxy mode, and write all traffic to <strong>outfile</strong>.</p> <h4 id="filtering-saved-traffic"><a class="anchor" href="#filtering-saved-traffic"># </a>Filtering saved traffic</h4> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mitmdump -nr infile -w outfile <span class="s2">"~m post"</span> </span></span></code></pre></div><p>Start mitmdump without binding to the proxy port (<code>-n</code>), read all flows from infile, apply the specified filter expression (only match POSTs), and write to outfile.</p> <h4 id="client-replay"><a class="anchor" href="#client-replay"># </a>Client replay</h4> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mitmdump -nC outfile </span></span></code></pre></div><p>Start mitmdump without binding to the proxy port (<code>-n</code>), then replay all requests from outfile (<code>-C filename</code>). Flags combine in the obvious way, so you can replay requests from one file, and write the resulting flows to another:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mitmdump -nC srcfile -w dstfile </span></span></code></pre></div><p>See the <a href="./overview-features/#client-side-replay">client-side replay</a> section for more information.</p> <h4 id="running-a-script"><a class="anchor" href="#running-a-script"># </a>Running a script</h4> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mitmdump -s examples/simple/add_header.py </span></span></code></pre></div><p>This runs the <strong>add_header.py</strong> example script, which simply adds a new header to all responses.</p> <h4 id="scripted-data-transformation"><a class="anchor" href="#scripted-data-transformation"># </a>Scripted data transformation</h4> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mitmdump -ns examples/simple/add_header.py -r srcfile -w dstfile </span></span></code></pre></div><p>This command loads flows from <strong>srcfile</strong>, transforms it according to the specified script, then writes it back to <strong>dstfile</strong>.</p> </div> </div> </body> </html>