1 files changed, 115 insertions, 0 deletions
diff --git a/doc-src/mitmproxy.html b/doc-src/mitmproxy.html
new file mode 100644
index 00000000..d41c1b21
--- /dev/null
+++ b/doc-src/mitmproxy.html
@@ -0,0 +1,115 @@
+
+__mitmproxy__ 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 _?_ shortcut key to view, context-sensitive
+documentation from any __mitmproxy__ screen.
+
+## Flow list
+
+The flow list shows an index of captured flows in chronological order. 
+
+<img src="@!urlTo('screenshots/mitmproxy.png')!@"/>
+
+- __1__: A GET request, returning a 302 Redirect response.
+- __2__: A GET request, returning 16.75kb of text/html data.
+- __3__: A replayed request. 
+- __4__: Intercepted flows are indicated with orange text. The user may edit
+these flows, and then accept them (using the _a_ key) to continue. In this
+case, the request has been intercepted on the way to the server.
+- __5__: A response intercepted from the server on the way to the client.
+- __6__: The event log can be toggled on and off using the _e_ shortcut key. This
+pane shows events and errors that may not result in a flow that shows up in the
+flow pane.
+- __7__: Flow count.
+- __8__: Various information on mitmproxy's state. In this case, we have an
+interception pattern set to ".*".
+- __9__: Bind address indicator - mitmproxy is listening on port 8080 of all
+interfaces.
+
+
+## Flow view
+
+The __Flow View__ lets you inspect and manipulate a single flow:
+
+<img src="@!urlTo('screenshots/mitmproxy-flowview.png')!@"/>
+
+- __1__: Flow summary.
+- __2__: 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 _tab_
+to switch between the Response and the Request.
+- __3__: Headers.
+- __4__: Body.
+- __5__: View Mode indicator. In this case, we're viewing the body in __hex__
+mode. The other available modes are __pretty__, which uses a number of
+heuristics to show you a friendly view of various content types, and __raw__,
+which shows you exactly what's there without any changes. You can change modes
+using the _m_ key.
+
+
+
+## Grid Editor
+
+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. 
+
+At the moment, the Grid Editor is used in four parts of mitmproxy:
+
+- Editing request or response headers (_e_ for edit, then _h_ for headers in flow view) 
+- Editing a query string (_e_ for edit, then _q_ for query in flow view)
+- Editing a URL-encoded form (_e_ for edit, then _f_ for form in flow view)
+- Editing replacement patterns (_R_ globally)
+
+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:
+
+<img src="@!urlTo('screenshots/mitmproxy-kveditor.png')!@"/>
+
+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:
+
+<img src="@!urlTo('screenshots/mitmproxy-kveditor-editmode.png')!@"/>
+
+Modify the field as desired, then press escape to exit edit mode when you're
+done. You can also add a row (_a_ key), delete a row (_d_ key), spawn an
+external editor on a field (_e_ key). Be sure to consult the context-sensitive
+help (_?_ key) for more.
+
+
+# Example: Interception
+
+__mitmproxy__'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. 
+
+
+### 1: Set an interception pattern
+
+<img src="@!urlTo('mitmproxy-intercept-filt.png')!@"/>
+
+We press _i_ to set an interception pattern. In this case, the __~q__ filter
+pattern tells __mitmproxy__ to intercept all requests. For complete filter
+syntax, see the [Filter expressions](@!urlTo("filters.html")!@) section of this
+document, or the built-in help function in __mitmproxy__.
+
+### 2: Intercepted connections are indicated with orange text:
+
+<img src="@!urlTo('mitmproxy-intercept-mid.png')!@"/>
+
+### 3: You can now view and modify the request:
+
+<img src="@!urlTo('mitmproxy-intercept-options.png')!@"/>
+
+In this case, we viewed the request by selecting it, pressed _e_ for "edit"
+and _m_ for "method" to change the HTTP request method.
+
+### 4: Accept the intercept to continue:
+
+<img src="@!urlTo('mitmproxy-intercept-result.png')!@"/>
+
+Finally, we press _a_ 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".