diff options
author | Aldo Cortesi <aldo@nullcube.com> | 2012-02-22 17:17:13 +1300 |
---|---|---|
committer | Aldo Cortesi <aldo@nullcube.com> | 2012-02-22 17:17:13 +1300 |
commit | 4f38b3a9c0dbbdf4bcd5e48386f3282263e2b5da (patch) | |
tree | 30f98cb6dd72f5515355d97bb1cc7815f620a3a5 /doc-src | |
parent | a4270efaf281dac9392f412739a6aa6fdda9a016 (diff) | |
download | mitmproxy-4f38b3a9c0dbbdf4bcd5e48386f3282263e2b5da.tar.gz mitmproxy-4f38b3a9c0dbbdf4bcd5e48386f3282263e2b5da.tar.bz2 mitmproxy-4f38b3a9c0dbbdf4bcd5e48386f3282263e2b5da.zip |
Documentation and screenshots.
Diffstat (limited to 'doc-src')
-rw-r--r-- | doc-src/mitmproxy.html | 89 | ||||
-rw-r--r-- | doc-src/screenshots/intercept-filt.png | bin | 30803 -> 0 bytes | |||
-rw-r--r-- | doc-src/screenshots/intercept-mid.png | bin | 35169 -> 0 bytes | |||
-rw-r--r-- | doc-src/screenshots/intercept-options.png | bin | 73210 -> 0 bytes | |||
-rw-r--r-- | doc-src/screenshots/intercept-result.png | bin | 40965 -> 0 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-flowview.png | bin | 0 -> 341726 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-intercept-filt.png | bin | 0 -> 22126 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-intercept-mid.png | bin | 0 -> 24129 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-intercept-options.png | bin | 0 -> 56232 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-intercept-result.png | bin | 0 -> 27773 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-kveditor-editmode.png | bin | 0 -> 61397 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy-kveditor.png | bin | 0 -> 62207 bytes | |||
-rw-r--r-- | doc-src/screenshots/mitmproxy.png | bin | 71881 -> 165272 bytes | |||
-rw-r--r-- | doc-src/scripts.html | 40 |
14 files changed, 93 insertions, 36 deletions
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. <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_ 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: +<img src="@!urlTo("screenshots/mitmproxy-flowview.png")!@"/> -## 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: + +<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, 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 -<img src="@!urlTo('intercept-filt.png')!@"/> +<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 a red exclamation mark: +### 2: Intercepted connections are indicated with orange text: -<img src="@!urlTo('intercept-mid.png')!@"/> +<img src="@!urlTo('mitmproxy-intercept-mid.png')!@"/> ### 3: You can now view and modify the request: -<img src="@!urlTo('intercept-options.png')!@"/> +<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 +### 4: Accept the intercept to continue: -<img src="@!urlTo('intercept-result.png')!@"/> +<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 to diff --git a/doc-src/screenshots/intercept-filt.png b/doc-src/screenshots/intercept-filt.png Binary files differdeleted file mode 100644 index f5d20947..00000000 --- a/doc-src/screenshots/intercept-filt.png +++ /dev/null diff --git a/doc-src/screenshots/intercept-mid.png b/doc-src/screenshots/intercept-mid.png Binary files differdeleted file mode 100644 index 2933f1cf..00000000 --- a/doc-src/screenshots/intercept-mid.png +++ /dev/null diff --git a/doc-src/screenshots/intercept-options.png b/doc-src/screenshots/intercept-options.png Binary files differdeleted file mode 100644 index ef987b04..00000000 --- a/doc-src/screenshots/intercept-options.png +++ /dev/null diff --git a/doc-src/screenshots/intercept-result.png b/doc-src/screenshots/intercept-result.png Binary files differdeleted file mode 100644 index 3d58104d..00000000 --- a/doc-src/screenshots/intercept-result.png +++ /dev/null diff --git a/doc-src/screenshots/mitmproxy-flowview.png b/doc-src/screenshots/mitmproxy-flowview.png Binary files differnew file mode 100644 index 00000000..b45b8b60 --- /dev/null +++ b/doc-src/screenshots/mitmproxy-flowview.png diff --git a/doc-src/screenshots/mitmproxy-intercept-filt.png b/doc-src/screenshots/mitmproxy-intercept-filt.png Binary files differnew file mode 100644 index 00000000..0f53e7c7 --- /dev/null +++ b/doc-src/screenshots/mitmproxy-intercept-filt.png diff --git a/doc-src/screenshots/mitmproxy-intercept-mid.png b/doc-src/screenshots/mitmproxy-intercept-mid.png Binary files differnew file mode 100644 index 00000000..1795bd1a --- /dev/null +++ b/doc-src/screenshots/mitmproxy-intercept-mid.png diff --git a/doc-src/screenshots/mitmproxy-intercept-options.png b/doc-src/screenshots/mitmproxy-intercept-options.png Binary files differnew file mode 100644 index 00000000..3558e5a8 --- /dev/null +++ b/doc-src/screenshots/mitmproxy-intercept-options.png diff --git a/doc-src/screenshots/mitmproxy-intercept-result.png b/doc-src/screenshots/mitmproxy-intercept-result.png Binary files differnew file mode 100644 index 00000000..4b55984d --- /dev/null +++ b/doc-src/screenshots/mitmproxy-intercept-result.png diff --git a/doc-src/screenshots/mitmproxy-kveditor-editmode.png b/doc-src/screenshots/mitmproxy-kveditor-editmode.png Binary files differnew file mode 100644 index 00000000..746d1e50 --- /dev/null +++ b/doc-src/screenshots/mitmproxy-kveditor-editmode.png diff --git a/doc-src/screenshots/mitmproxy-kveditor.png b/doc-src/screenshots/mitmproxy-kveditor.png Binary files differnew file mode 100644 index 00000000..64169d50 --- /dev/null +++ b/doc-src/screenshots/mitmproxy-kveditor.png diff --git a/doc-src/screenshots/mitmproxy.png b/doc-src/screenshots/mitmproxy.png Binary files differindex 4dad7728..28244a0d 100644 --- a/doc-src/screenshots/mitmproxy.png +++ b/doc-src/screenshots/mitmproxy.png 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: <table class="kvtable"> <tr> - <th>libmproxy.flow.ScriptContext</th> - <td>A handle for interacting with mitmproxy's global state.</td> + <th>libmproxy.flow.ClientConnection</th> + <td>Describes a client connection.</td> </tr> <tr> - <th>libmproxy.flow.Flow</th> - <td>A collection of objects representing a single HTTP transaction.</td> + <th>libmproxy.flow.ClientDisconnection</th> + <td>Describes a client disconnection.</td> </tr> <tr> - <th>libmproxy.flow.Request</th> - <td>An HTTP request.</td> + <th>libmproxy.flow.Error</th> + <td>A communications error.</td> </tr> <tr> - <th>libmproxy.flow.Response</th> - <td>An HTTP response.</td> + <th>libmproxy.flow.Flow</th> + <td>A collection of objects representing a single HTTP transaction.</td> </tr> <tr> - <th>libmproxy.flow.Error</th> - <td>A communications error.</td> + <th>libmproxy.flow.Headers</th> + <td>HTTP headers for a request or response.</td> </tr> <tr> - <th>libmproxy.flow.ClientConnection</th> - <td>Describes a client connection.</td> + <th>libmproxy.flow.ODict</th> + + <td>A dictionary-like object for managing sets of key/value data. There + is also a variant called CaselessODict that ignores key case for some + calls.</td> </tr> <tr> - <th>libmproxy.flow.ClientDisconnection</th> - <td>Describes a client disconnection.</td> + <th>libmproxy.flow.Response</th> + <td>An HTTP response.</td> </tr> <tr> - <th>libmproxy.flow.Headers</th> - <td>HTTP headers for a request or response.</td> + <th>libmproxy.flow.Request</th> + <td>An HTTP request.</td> + </tr> + <tr> + <th>libmproxy.flow.ScriptContext</th> + <td>A handle for interacting with mitmproxy's global state.</td> </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: |