diff options
| -rw-r--r-- | doc-src/_layout.html | 5 | ||||
| -rw-r--r-- | doc-src/dev/addingviews.html | 52 | ||||
| -rw-r--r-- | doc-src/dev/index.py | 6 | ||||
| -rw-r--r-- | doc-src/dev/testing.html | 43 | ||||
| -rw-r--r-- | doc-src/howmitmproxy.html | 2 | ||||
| -rw-r--r-- | doc-src/index.py | 2 | ||||
| -rw-r--r-- | doc-src/install.html | 2 | ||||
| -rw-r--r-- | doc-src/scripting/addingviews.html | 36 | ||||
| -rw-r--r-- | doc-src/scripting/index.py | 1 | ||||
| -rw-r--r-- | libmproxy/version.py | 2 |
10 files changed, 109 insertions, 42 deletions
diff --git a/doc-src/_layout.html b/doc-src/_layout.html index a361f764..72b27cd3 100644 --- a/doc-src/_layout.html +++ b/doc-src/_layout.html @@ -58,7 +58,10 @@ <li class="nav-header">Scripting mitmproxy</li> $!nav("scripting/inlinescripts.html", this, state)!$ $!nav("scripting/libmproxy.html", this, state)!$ - $!nav("scripting/addingviews.html", this, state)!$ + + <li class="nav-header">Hacking</li> + $!nav("dev/testing.html", this, state)!$ + </ul> </div> </div> diff --git a/doc-src/dev/addingviews.html b/doc-src/dev/addingviews.html new file mode 100644 index 00000000..12623a31 --- /dev/null +++ b/doc-src/dev/addingviews.html @@ -0,0 +1,52 @@ +As discussed in [the Flow View section of the mitmproxy +overview](@!urlTo("mitmproxy.html")!@), mitmproxy allows you to inspect and +manipulate flows. When inspecting a single flow, mitmproxy uses a number of +heuristics to show a friendly view of various content types; if mitmproxy +cannot show a friendly view, mitmproxy defaults to a __raw__ view. + +Each content type invokes a different flow viewer to parse the data and display +the friendly view. Users can add custom content viewers by adding a view class +to contentview.py, discussed below. + +## Adding a new View class to contentview.py + +The content viewers used by mitmproxy to present a friendly view of various +content types are stored in contentview.py. Reviewing this file shows a number +of classes named ViewSomeDataType, each with the properties: __name__, +__prompt__, and __content\_types__ and a function named __\_\_call\_\___. + +Adding a new content viewer to parse a data type is as simple as writing a new +View class. Your new content viewer View class should have the same properties +as the other View classes: __name__, __prompt__, and __content\_types__ and a +__\_\_call\_\___ function to parse the content of the request/response. + +* The __name__ property should be a string describing the contents and new content viewer; +* The __prompt__ property should be a two item tuple: + + - __1__: A string that will be used to display the new content viewer's type; and + - __2__: A one character string that will be the hotkey used to select the new content viewer from the Flow View screen; + +* The __content\_types__ property should be a list of strings of HTTP Content\-Types that the new content viewer can parse. + * Note that mitmproxy will use the content\_types to try and heuristically show a friendly view of content and that you can override the built-in views by populating content\_types with values for content\_types that are already parsed -- e.g. "image/png". + +After defining the __name__, __prompt__, and __content\_types__ properties of +the class, you should write the __\_\_call\_\___ function, which will parse the +request/response data and provide a friendly view of the data. The +__\_\_call\_\___ function should take the following arguments: __self__, +__hdrs__, __content__, __limit__; __hdrs__ is a ODictCaseless object containing +the headers of the request/response; __content__ is the content of the +request/response, and __limit__ is an integer representing the amount of data +to display in the view window. + +The __\_\_call\_\___ function returns two values: (1) a string describing the +parsed data; and (2) the parsed data for friendly display. The parsed data to +be displayed should be a list of strings formatted for display. You can use +the __\_view\_text__ function in contentview.py to format text for display. +Alternatively, you can display content as a series of key-value pairs; to do +so, prepare a list of lists, where each list item is a two item list -- a key +that describes the data, and then the data itself; after preparing the list of +lists, use the __common.format\_keyvals__ function on it to prepare it as text +for display. + +If the new content viewer fails or throws an exception, mitmproxy will default +to a __raw__ view. diff --git a/doc-src/dev/index.py b/doc-src/dev/index.py new file mode 100644 index 00000000..001c2b89 --- /dev/null +++ b/doc-src/dev/index.py @@ -0,0 +1,6 @@ +from countershape import Page + +pages = [ + Page("testing.html", "Testing"), +# Page("addingviews.html", "Writing Content Views"), +] diff --git a/doc-src/dev/testing.html b/doc-src/dev/testing.html new file mode 100644 index 00000000..4cee29e8 --- /dev/null +++ b/doc-src/dev/testing.html @@ -0,0 +1,43 @@ + +All the mitmproxy projects strive to maintain 100% code coverage. In general, +patches and pull requests will be declined unless they're accompanied by a +suitable extension to the test suite. + +Our tests are written for the [nose](https://nose.readthedocs.org/en/latest/). +At the point where you send your pull request, a command like this: + +<pre class="terminal"> +> nosetests --with-cov --cov-report term-missing ./test +</pre> + +Should give output something like this: + +<pre class="terminal"> +> ---------- coverage: platform darwin, python 2.7.2-final-0 -- +> Name Stmts Miss Cover Missing +> ---------------------------------------------------- +> libmproxy/__init__ 0 0 100% +> libmproxy/app 4 0 100% +> libmproxy/cmdline 100 0 100% +> libmproxy/controller 69 0 100% +> libmproxy/dump 150 0 100% +> libmproxy/encoding 39 0 100% +> libmproxy/filt 201 0 100% +> libmproxy/flow 891 0 100% +> libmproxy/proxy 427 0 100% +> libmproxy/script 27 0 100% +> libmproxy/utils 133 0 100% +> libmproxy/version 4 0 100% +> ---------------------------------------------------- +> TOTAL 2045 0 100% +> ---------------------------------------------------- +> Ran 251 tests in 11.864s +</pre> + + +There are exceptions to the coverage requirement - for instance, much of the +console interface code can't sensibly be unit tested. These portions are +excluded from coverage analysis either in the **.coveragerc** file, or using +**#pragma no-cover** directives. To keep our coverage analysis relevant, we use +these measures as sparingly as possible. + diff --git a/doc-src/howmitmproxy.html b/doc-src/howmitmproxy.html index 09a69ec2..94afd522 100644 --- a/doc-src/howmitmproxy.html +++ b/doc-src/howmitmproxy.html @@ -246,7 +246,7 @@ mechanism has a different way of exposing this data, so this introduces the second component required for working transparent proxying: a host module that knows how to retrieve the original destination address from the router. In mitmproxy, this takes the form of a built-in set of -[modules](https://github.com/cortesi/mitmproxy/tree/master/libmproxy/platform) +[modules](https://github.com/mitmproxy/mitmproxy/tree/master/libmproxy/platform) that know how to talk to each platform's redirection mechanism. Once we have this information, the process is fairly straight-forward. diff --git a/doc-src/index.py b/doc-src/index.py index 7b84f982..6880bcae 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -5,7 +5,7 @@ import countershape.template sys.path.insert(0, "..") from libmproxy import filt -MITMPROXY_SRC = "~/git/public/mitmproxy" +MITMPROXY_SRC = "~/mitmproxy/mitmproxy" if ns.options.website: ns.idxpath = "doc/index.html" diff --git a/doc-src/install.html b/doc-src/install.html index 30e2774d..70003d60 100644 --- a/doc-src/install.html +++ b/doc-src/install.html @@ -25,7 +25,7 @@ pip install /path/to/source </pre> Note that if you're installing current git master, you will also have to -install the current git master of [netlib](http://github.com/cortesi/netlib) by +install the current git master of [netlib](http://github.com/mitmproxy/netlib) by hand. ## OSX diff --git a/doc-src/scripting/addingviews.html b/doc-src/scripting/addingviews.html deleted file mode 100644 index 2191cae7..00000000 --- a/doc-src/scripting/addingviews.html +++ /dev/null @@ -1,36 +0,0 @@ -As discussed in [the Flow View section of the mitmproxy overview](@!urlTo("mitmproxy.html")!@), mitmproxy allows you to inspect and manipulate flows. When inspecting a single flow, mitmproxy uses a number of heuristics to show a friendly view of various content types; if mitmproxy cannot show a friendly view, mitmproxy defaults to a __raw__ view. - -By default, mitmproxy has support for displaying the following content types in a friendly view: - -- __1__: Hex -- __2__: HTML -- __3__: Image -- __4__: JavaScript -- __5__: JSON -- __6__: URL-encoded data -- __7__: XML -- __8__: AMF (requires PyAMF) -- __9__: Protobuf (requires protobuf library) - -Each content type invokes a different flow viewer to parse the data and display the friendly view. Users can add custom content viewers by adding a view class to contentview.py, discussed below. - -## Adding a new View class to contentview.py - -The content viewers used by mitmproxy to present a friendly view of various content types are stored in contentview.py. Reviewing this file shows a number of classes named ViewSomeDataType, each with the properties: __name__, __prompt__, and __content\_types__ and a function named __\_\_call\_\___. - -Adding a new content viewer to parse a data type is as simple as writing a new View class. Your new content viewer View class should have the same properties as the other View classes: __name__, __prompt__, and __content\_types__ and a __\_\_call\_\___ function to parse the content of the request/response. - -* The __name__ property should be a string describing the contents and new content viewer; -* The __prompt__ property should be a two item tuple: - - - __1__: A string that will be used to display the new content viewer's type; and - - __2__: A one character string that will be the hotkey used to select the new content viewer from the Flow View screen; - -* The __content\_types__ property should be a list of strings of HTTP Content\-Types that the new content viewer can parse. - * Note that mitmproxy will use the content\_types to try and heuristically show a friendly view of content and that you can override the built-in views by populating content\_types with values for content\_types that are already parsed -- e.g. "image/png". - -After defining the __name__, __prompt__, and __content\_types__ properties of the class, you should write the __\_\_call\_\___ function, which will parse the request/response data and provide a friendly view of the data. The __\_\_call\_\___ function should take the following arguments: __self__, __hdrs__, __content__, __limit__; __hdrs__ is a ODictCaseless object containing the headers of the request/response; __content__ is the content of the request/response, and __limit__ is an integer representing the amount of data to display in the view window. - -The __\_\_call\_\___ function returns two values: (1) a string describing the parsed data; and (2) the parsed data for friendly display. The parsed data to be displayed should be a list of strings formatted for display. You can use the __\_view\_text__ function in contentview.py to format text for display. Alternatively, you can display content as a series of key-value pairs; to do so, prepare a list of lists, where each list item is a two item list -- a key that describes the data, and then the data itself; after preparing the list of lists, use the __common.format\_keyvals__ function on it to prepare it as text for display. - -If the new content viewer fails or throws an exception, mitmproxy will default to a __raw__ view. diff --git a/doc-src/scripting/index.py b/doc-src/scripting/index.py index 27dc6f00..b8312083 100644 --- a/doc-src/scripting/index.py +++ b/doc-src/scripting/index.py @@ -3,5 +3,4 @@ from countershape import Page pages = [ Page("inlinescripts.html", "Inline Scripts"), Page("libmproxy.html", "libmproxy"), - Page("addingviews.html","Adding new content viewers") ] diff --git a/libmproxy/version.py b/libmproxy/version.py index 3dfc9409..b3a9bd95 100644 --- a/libmproxy/version.py +++ b/libmproxy/version.py @@ -1,4 +1,4 @@ -IVERSION = (0, 9) +IVERSION = (0, 9, 1) VERSION = ".".join(str(i) for i in IVERSION) NAME = "mitmproxy" NAMEVERSION = NAME + " " + VERSION |