From 4f38b3a9c0dbbdf4bcd5e48386f3282263e2b5da Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Wed, 22 Feb 2012 17:17:13 +1300 Subject: Documentation and screenshots. --- doc-src/mitmproxy.html | 89 ++++++++++++++++----- doc-src/screenshots/intercept-filt.png | Bin 30803 -> 0 bytes doc-src/screenshots/intercept-mid.png | Bin 35169 -> 0 bytes doc-src/screenshots/intercept-options.png | Bin 73210 -> 0 bytes doc-src/screenshots/intercept-result.png | Bin 40965 -> 0 bytes doc-src/screenshots/mitmproxy-flowview.png | Bin 0 -> 341726 bytes doc-src/screenshots/mitmproxy-intercept-filt.png | Bin 0 -> 22126 bytes doc-src/screenshots/mitmproxy-intercept-mid.png | Bin 0 -> 24129 bytes .../screenshots/mitmproxy-intercept-options.png | Bin 0 -> 56232 bytes doc-src/screenshots/mitmproxy-intercept-result.png | Bin 0 -> 27773 bytes .../screenshots/mitmproxy-kveditor-editmode.png | Bin 0 -> 61397 bytes doc-src/screenshots/mitmproxy-kveditor.png | Bin 0 -> 62207 bytes doc-src/screenshots/mitmproxy.png | Bin 71881 -> 165272 bytes doc-src/scripts.html | 40 +++++---- 14 files changed, 93 insertions(+), 36 deletions(-) delete mode 100644 doc-src/screenshots/intercept-filt.png delete mode 100644 doc-src/screenshots/intercept-mid.png delete mode 100644 doc-src/screenshots/intercept-options.png delete mode 100644 doc-src/screenshots/intercept-result.png create mode 100644 doc-src/screenshots/mitmproxy-flowview.png create mode 100644 doc-src/screenshots/mitmproxy-intercept-filt.png create mode 100644 doc-src/screenshots/mitmproxy-intercept-mid.png create mode 100644 doc-src/screenshots/mitmproxy-intercept-options.png create mode 100644 doc-src/screenshots/mitmproxy-intercept-result.png create mode 100644 doc-src/screenshots/mitmproxy-kveditor-editmode.png create mode 100644 doc-src/screenshots/mitmproxy-kveditor.png (limited to 'doc-src') diff --git a/doc-src/mitmproxy.html b/doc-src/mitmproxy.html index ef0b242d..d1d51da3 100644 --- a/doc-src/mitmproxy.html +++ b/doc-src/mitmproxy.html @@ -1,28 +1,79 @@ __mitmproxy__ is a console tool that allows interactive examination and -modification of HTTP traffic. The _?_ shortcut key shows complete documentation -on __mitmproxy__'s functionality. +modification of HTTP traffic. Use the _?_ shortcut key to view, +context-sensitive documentation from any __mitmproxy__ screen. +## Flow list -## The interface: connection list +The flow list shows an index of captured flows in chronological order. +- __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_ shorcut 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. -The connection list shows an index of captured flows in chronological order. -So, in this case, we can we can see that we visited __gmail.com__, which then -returned a 301 redirect to mail.google.com. -The statusbar at the bottom tells us that there are 11 flows in the view, that -we are using the "pretty" view mode (more on that below), and that the proxy is -bound to port 8080 of all interfaces. +## Flow view -Also visible is the __Event log__, which can be toggled on and off with the _v_ -keyboard shortcut. This displays events like client connection information, -errors, and script output. +The __Flow View__ lets you inspect and manipulate a single flow: + -## Example: Interception +- __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. + + +## Key/Value Editor + +It turns out that ordered key/value data is pervasive in HTTP communications, +so mitmproxy has a built-in editor to help edit and create this kind of data. +There are three ways to reach the __K/V Editor__ from the __Flow View__ screen: + +- Editing request or response headers (_e_ for edit, then _h_ for headers) +- Editing a query string (_e_ for edit, then _q_ for query) +- Editing a URL-encoded form (_e_ for edit, then _f_ for form) + +If there is is no form or query string, an empty __K/V Editor__ will be started +to let you add one. Here is the __K/V Editor__ showing the headers from a +request: + + + +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: + + + +Modify the field as desired, and press escape or enter to exit edit mode when +you're done. You can also add a key/value pair (_a_ key), delete a pair (_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 @@ -31,27 +82,27 @@ or client. ### 1: Set an interception pattern - + 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 a red exclamation mark: +### 2: Intercepted connections are indicated with orange text: - + ### 3: You can now view and modify the request: - + 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 +### 4: Accept the intercept to continue: - + 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 to diff --git a/doc-src/screenshots/intercept-filt.png b/doc-src/screenshots/intercept-filt.png deleted file mode 100644 index f5d20947..00000000 Binary files a/doc-src/screenshots/intercept-filt.png and /dev/null differ diff --git a/doc-src/screenshots/intercept-mid.png b/doc-src/screenshots/intercept-mid.png deleted file mode 100644 index 2933f1cf..00000000 Binary files a/doc-src/screenshots/intercept-mid.png and /dev/null differ diff --git a/doc-src/screenshots/intercept-options.png b/doc-src/screenshots/intercept-options.png deleted file mode 100644 index ef987b04..00000000 Binary files a/doc-src/screenshots/intercept-options.png and /dev/null differ diff --git a/doc-src/screenshots/intercept-result.png b/doc-src/screenshots/intercept-result.png deleted file mode 100644 index 3d58104d..00000000 Binary files a/doc-src/screenshots/intercept-result.png and /dev/null differ diff --git a/doc-src/screenshots/mitmproxy-flowview.png b/doc-src/screenshots/mitmproxy-flowview.png new file mode 100644 index 00000000..b45b8b60 Binary files /dev/null and b/doc-src/screenshots/mitmproxy-flowview.png differ diff --git a/doc-src/screenshots/mitmproxy-intercept-filt.png b/doc-src/screenshots/mitmproxy-intercept-filt.png new file mode 100644 index 00000000..0f53e7c7 Binary files /dev/null and b/doc-src/screenshots/mitmproxy-intercept-filt.png differ diff --git a/doc-src/screenshots/mitmproxy-intercept-mid.png b/doc-src/screenshots/mitmproxy-intercept-mid.png new file mode 100644 index 00000000..1795bd1a Binary files /dev/null and b/doc-src/screenshots/mitmproxy-intercept-mid.png differ diff --git a/doc-src/screenshots/mitmproxy-intercept-options.png b/doc-src/screenshots/mitmproxy-intercept-options.png new file mode 100644 index 00000000..3558e5a8 Binary files /dev/null and b/doc-src/screenshots/mitmproxy-intercept-options.png differ diff --git a/doc-src/screenshots/mitmproxy-intercept-result.png b/doc-src/screenshots/mitmproxy-intercept-result.png new file mode 100644 index 00000000..4b55984d Binary files /dev/null and b/doc-src/screenshots/mitmproxy-intercept-result.png differ diff --git a/doc-src/screenshots/mitmproxy-kveditor-editmode.png b/doc-src/screenshots/mitmproxy-kveditor-editmode.png new file mode 100644 index 00000000..746d1e50 Binary files /dev/null and b/doc-src/screenshots/mitmproxy-kveditor-editmode.png differ diff --git a/doc-src/screenshots/mitmproxy-kveditor.png b/doc-src/screenshots/mitmproxy-kveditor.png new file mode 100644 index 00000000..64169d50 Binary files /dev/null and b/doc-src/screenshots/mitmproxy-kveditor.png differ diff --git a/doc-src/screenshots/mitmproxy.png b/doc-src/screenshots/mitmproxy.png index 4dad7728..28244a0d 100644 Binary files a/doc-src/screenshots/mitmproxy.png and b/doc-src/screenshots/mitmproxy.png differ diff --git a/doc-src/scripts.html b/doc-src/scripts.html index f3df489d..bea8a103 100644 --- a/doc-src/scripts.html +++ b/doc-src/scripts.html @@ -63,40 +63,46 @@ The main classes you will deal with in writing mitmproxy scripts are: - - + + - - + + - - + + - - + + - - + + - - + + + - - + + - - + + + + + +
libmproxy.flow.ScriptContextA handle for interacting with mitmproxy's global state.libmproxy.flow.ClientConnectionDescribes a client connection.
libmproxy.flow.FlowA collection of objects representing a single HTTP transaction.libmproxy.flow.ClientDisconnectionDescribes a client disconnection.
libmproxy.flow.RequestAn HTTP request.libmproxy.flow.ErrorA communications error.
libmproxy.flow.ResponseAn HTTP response.libmproxy.flow.FlowA collection of objects representing a single HTTP transaction.
libmproxy.flow.ErrorA communications error.libmproxy.flow.HeadersHTTP headers for a request or response.
libmproxy.flow.ClientConnectionDescribes a client connection.libmproxy.flow.ODictA dictionary-like object for managing sets of key/value data. There + is also a variant called CaselessODict that ignores key case for some + calls.
libmproxy.flow.ClientDisconnectionDescribes a client disconnection.libmproxy.flow.ResponseAn HTTP response.
libmproxy.flow.HeadersHTTP headers for a request or response.libmproxy.flow.RequestAn HTTP request.
libmproxy.flow.ScriptContextA handle for interacting with mitmproxy's global state.
- The canonical API documentation is the code. You can view the API documentation using pydoc (which is installed with Python by default), like this: -- cgit v1.2.3