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 +++++---- libmproxy/console/__init__.py | 1 - libmproxy/console/common.py | 6 +- libmproxy/flow.py | 22 ++++- 17 files changed, 115 insertions(+), 43 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 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: diff --git a/libmproxy/console/__init__.py b/libmproxy/console/__init__.py index b07a6fe1..2f835189 100644 --- a/libmproxy/console/__init__.py +++ b/libmproxy/console/__init__.py @@ -318,7 +318,6 @@ class ConsoleMaster(flow.FlowMaster): ('heading_key', "q"), ":back", ] footer_text_flowview = [ - ('heading_key', "tab"), ":toggle view ", ('heading_key', "?"), ":help ", ('heading_key', "q"), ":back ", ] diff --git a/libmproxy/console/common.py b/libmproxy/console/common.py index fbeb83d7..d1c6303a 100644 --- a/libmproxy/console/common.py +++ b/libmproxy/console/common.py @@ -84,6 +84,8 @@ def fcol(s, attr): +REPLAY_SYMBOL = u"\u21ba" + def format_flow(f, focus, extended=False, padding=2): pile = [] @@ -98,7 +100,7 @@ def format_flow(f, focus, extended=False, padding=2): else: req.append(fcol(">>" if focus else " ", "focus")) if f.request.is_replay(): - req.append(fcol(u"\u267B", "replay")) + req.append(fcol(REPLAY_SYMBOL, "replay")) req.append(fcol(f.request.method, "method")) preamble = sum(i[1] for i in req) + len(req) -1 @@ -126,7 +128,7 @@ def format_flow(f, focus, extended=False, padding=2): if f.response: if f.response.is_replay(): - resp.append(fcol(u"\u267B", "replay")) + resp.append(fcol(REPLAY_SYMBOL, "replay")) if f.response.code in [200, 304]: resp.append(fcol(f.response.code, "goodcode")) else: diff --git a/libmproxy/flow.py b/libmproxy/flow.py index f3bc39d8..4cde7bc9 100644 --- a/libmproxy/flow.py +++ b/libmproxy/flow.py @@ -58,6 +58,10 @@ class ODict: return self.lst == other.lst def __getitem__(self, k): + """ + Returns a list of values matching key. + + """ ret = [] k = self._kconv(k) for i in self.lst: @@ -73,18 +77,28 @@ class ODict: return new def __len__(self): + """ + Total number of (key, value) pairs. + """ return len(self.lst) - def __setitem__(self, k, values): - if isinstance(values, basestring): - raise ValueError("ODict values should be lists.") + def __setitem__(self, k, valuelist): + """ + Sets the values for key k. If there are existing values for this + key, they are cleared. + """ + if isinstance(valuelist, basestring): + raise ValueError("ODict valuelist should be lists.") k = self._kconv(k) new = self._filter_lst(k, self.lst) - for i in values: + for i in valuelist: new.append((k, i)) self.lst = new def __delitem__(self, k): + """ + Delete all items matching k. + """ self.lst = self._filter_lst(k, self.lst) def __contains__(self, k): -- cgit v1.2.3